1
*These are the porting notes to OpenVMS, as of 7 April 2010
2
by Jose Baars. This file will be installed as
3
libssh2*.release_notes by the product install kit.
9
LIBSSH2 is a client-side library written in C that aims to
10
implement the SSH2 protocol. It is an open source project,
11
to be found at https://libssh2.org.
16
The library uses the GNV prefix, on advise of the kind supporter
17
of the GNV project, John Malmberg.
19
Installing the PCSI kit
20
=======================
24
- VMS version 8.3 minimal.
25
See the remarks at prerequisites for building the kit
26
- TCP/IP stack, both TCP/IP services and Multinet should work.
27
See the remarks at prerequisites for building the kit
28
- HP OPENSSL V1.3 minimal.
29
See the remarks at prerequisites for building the kit
30
- JEM ZLIB V1.2-3E1 minimal.
31
See the remarks at prerequisites for building the kit
33
The first three dependencies are tested at installation time, and
34
installation will fail if any these products are not installed.
35
The ZLIB dependency is not tested by the product installation
36
procedure, as libssh2 will probably be installed as part of
37
multiple libraries including zlib.
43
The kit will install gnv$libssh2.exe in a directory tree that might
44
already be available on your system if you have installed other gnv*
45
libraries or utilities.
47
The directory tree for gnv$libssh2.exe will be like this:
49
[gnv] -- [usr] -- [include] -- [libssh2] include files for libssh2
50
[lib] gnv$libssh2_x_y_z.exe
51
[share] -- [doc] -- [libssh2] libssh2.hlb,
52
release notes (this file),
56
[example] libssh2_examples-x_y_z.bck
57
[common_src] libssh2-x_y_z_src.bck
59
By default, it will install the shared image and include files to
62
You can override this destination by specifying the destination
63
directory after /DESTINATION= on the product install command line.
64
This is particularly of use when installing the library on a cluster
65
without a common system disk.
67
Please ignore the following warnings, as the kit is not signed :
69
%PCSI-I-CANNOTVAL, cannot validate dev:[dir]JCB-AXPVMS-LIBSSH2-V0102-05D20100402-1.PCSI
70
-PCSI-I-NOTSIGNED, product kit is not signed and therefore has no manifest file
72
Optionally, you can install a backup saveset with some programming examples,
73
or a backupo saveset with the complete libssh2 source tree.
75
you will need to answer 'NO' to the question
76
'Do you want the default for all options'.
78
and 'YES' to either or both the following questions:
80
Do you want the libssh2 C programming examples ? [NO]
82
Do you want the complete libssh2 source tree ? [NO]
85
Post installation tasks
86
-----------------------
88
Although we will try to maintain upward compatibility of libssh2,
89
this can not be guaranteed by the libssh2 project itself for OpenVMS,
92
To use libssh2 effectively, you will have to define a system logical
93
to point to the shared image. If you are willing to take the gamble,
94
define this logical in your systartup like so:
96
$ define/system/executive gnv$libssh2 dev:[dir..]gnv$libssh2_x_y_z.exe
98
Optionally, you can install the executable like so:
100
$ mc sysgen install dev:[dir..]gnv$libssh2_x_y_z.exe/open/share/header
102
Link your programs against gnv$libssh2, and when upgrading libssh2
105
If you want to be extra cautious define a system logical like this:
107
$ define/system/executive gnv$libssh2_x_y_z dev:[dir..]gnv$libssh2_x_y_z.exe
109
Link programs against gnv$libssh2_x_y_z, and when upgrading libssh2
110
link against new versions.
112
It is probably more convenient in the last case to link against the object
113
library provided in the source backup saveset. Both an uppercase and a
114
mixed case object library, called libssh2.olb and libssh2_asis.olb
118
Compiling and linking against libssh2
119
-------------------------------------
121
The shared image library has a vector table with both uppercase and
122
mixed case entry points, allowing to link directly against the shared
123
image whether you need the /NAMES=AS_IS or not.
125
To link successfully, you MUST use /NAMES=shortened, as some function
126
names in libssh2 are longer than the VMS maximum of 32 characters.
128
If you chose to install the examples, you can unpack the backup
131
backup/sel=*.c device:[gnv.usr.share.doc.libssh2.examples]libssh2_examples-x_y_z.bck -
134
They can by compiled and linked by these commands ( provided you have defined
135
the gnv$libssh2 logical) :
137
$ cc/include=dev:[gnv.usr.include.libssh2] xxx.c/names=shortened
138
$ link/opt=sys$input: xxx.obj
147
You can build gnv$libssh2 yourself, which may have advantages, as the library is
148
in full development, very regularly new features are added.
150
For production use, it is probably advisable to use a stable version, and
151
link against that. To check out new features, statically linking against
152
the object library is probably more practical, to avoid compatibility
159
You will need to have the following available:
161
- An Alpha or Itanium VMS system. Due to dependencies on zlib, ssl and ODS-5,
162
support on VAXen would be cumbersome at least.
164
- VMS version 8.3 minimal. This is a requirement of gnv$zlibshr.exe against
165
which shared image library libssh2 is linked. If you use another zlib
166
to link against, you can make it work under lower versions of VMS.
167
I have made it work on VMS 7.3-2 with not a lot of difficulty.
168
Also, if you are not interested in compression, you can choose not
169
to link against zlib at all; in that case comment out the
170
#define LIBSSH2_HAVE_ZLIB in libssh2_config.h.
172
- TCP/IP services or Multinet for OpenVMS.
173
TCPWare has not been tested.
175
- The HP OpenSSL product. Of course, with tweaking, you can probably link
176
it against the OpenSSL library, but that is not what I have used.
178
- A C compiler. I don't know any other working C compilers than
179
the DEC/Compac/HP-C compiler on VMS.
181
- An ODS-5 disk. With tweaking you'll get it to work on an ODS-2
182
disk, but it is unpractical to do so.
184
- A version of VMSTAR that understands ODS-5 disks and extended
185
filenames. Look here:
186
http://ftp.process.com/ftp/vms-freeware/fileserv/vmstar.zip
188
- gunzip, available for instance at Steven M Schweda's website:
189
http://antinode.info/ftp/gzip/gzip-1_3_12b_vms/gzip-1_3_12b_vms.zip
193
- curl, to be found at https://curl.haxx.se
194
You might want to use curl to download the libssh2 kit directly
195
to you VMS machine. Interestingly, sftp in curl is implemented using
196
libssh2, soon to be expected on VMS as well, hopefully.
201
At the website of libssh2, you can find stable and daily gzipped
202
tarballs. if you have a computer connected to internet you can
203
download a daily build yourself by a procedure that looks a lot like
204
this ( fill out your own proxy user/password, set up right symbols to
205
gunzip, vmstar and curl and set up the libssh2 build version):
207
$ libssh2_version = "1.2.6"
209
$ proxy_line = " ""-U"" ""''proxy_userpass'"" ""-x"" ""''proxy_hostport'"" "
211
$ currentday = f$cvtime(,,"date") - "-" - "-"
213
$ set def mydev:[mydir.libssh2]
215
$ if f$search("libssh2-''libssh2_version'-''currentday'.tar.gz") .nes. ""217
$ delete libssh2-'libssh2_version'-'currentday'.tar.gz;*
220
$ curl 'proxy_line' "https://libssh2.org/snapshots/libssh2-''libssh2_version'-''currentday'.tar.gz" -
221
-o libssh2-'libssh2_version'-'currentday'.tar.gz
224
$ if f$search("libssh2-''libssh2_version'-''currentday'.tar.;") .nes. ""226
$ delete libssh2-'libssh2_version'-'currentday'.tar.;*
229
$ gunzip libssh2-'libssh2_version'-'currentday'.tar.gz
231
$ tarfile = f$search("libssh2-''libssh2_version'-''currentday'.tar.;")234
Downloading a stable build will need you to get rid of the currentday.
236
After the download, you should have a directory tree with a toplevel
237
directory called [libssh2-x.y.z-yyyymmdd].
238
One of the subdirectories is called vms.
240
Getting the libssh2 sources from the source backup in the binary kit
241
--------------------------------------------------------------------
243
During installation of the binary kit, you are given the option
244
of installing the sources. If chosen, a backup saveset with
245
the complete libssh2 directory is made available in
248
By restoring this backup saveset, you end up with the same
249
set of files as by the direct download from libssh2.org.
255
To avoid all kinds of misunderstandings caused by firewalls thinking that
256
a .com file must be an MS-DOS executable, all command procedures are called
259
Go to the vms subdirectory in the download tree, and issue the following
264
This should produce libssh2_x_y_z.exe in this same vms directory.
271
A number of examples are also part of the full libssh2 delivery.
272
You can compile and link them either against the object library
273
produced when building the shared image, or against the shared image
274
produced in the step before.
276
You can compile only one of the examples by giving only the
277
name part of the filename of the example as p1 to the
280
@libssh2_make_example.dcl
284
@libssh2_make_example.dcl sftp
286
By default, libssh2_make_example.dcl links to the object libraries
287
produced by the libssh2_make_lib.dcl procedure. If you want to link
288
against the shared image library made in the same procedure, invoke
289
the procedure like so:
291
@libssh2_make_example.dcl sftp "SHARED"
293
The procedure defines a process logical gnv$libssh2 pointing to the shared
294
image library in the directory, which obviously will not survive a logout.
297
Building the help library
298
-------------------------
300
The man pages can be converted to a VMS help library by issuing
303
@libssh2_make_help.dcl
305
It uses a simple but fairly effective c program man2help.c
311
When you have built the shared library and the help library,
312
you can build a PCSI kit by issuing this command: