| 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. |
| 4 |
|
| 5 |
|
| 6 |
LIBSSH2 |
| 7 |
------- |
| 8 |
|
| 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. |
| 12 |
|
| 13 |
GNV |
| 14 |
--- |
| 15 |
|
| 16 |
The library uses the GNV prefix, on advise of the kind supporter |
| 17 |
of the GNV project, John Malmberg. |
| 18 |
|
| 19 |
Installing the PCSI kit |
| 20 |
======================= |
| 21 |
|
| 22 |
Prerequisites |
| 23 |
------------- |
| 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 |
| 32 |
|
| 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. |
| 38 |
|
| 39 |
Install |
| 40 |
------- |
| 41 |
|
| 42 |
|
| 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. |
| 46 |
|
| 47 |
The directory tree for gnv$libssh2.exe will be like this: |
| 48 |
|
| 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), |
| 53 |
libssh2 release notes |
| 54 |
|
| 55 |
optional: |
| 56 |
[example] libssh2_examples-x_y_z.bck |
| 57 |
[common_src] libssh2-x_y_z_src.bck |
| 58 |
|
| 59 |
By default, it will install the shared image and include files to |
| 60 |
SYS$COMMON:[GNV...]. |
| 61 |
|
| 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. |
| 66 |
|
| 67 |
Please ignore the following warnings, as the kit is not signed : |
| 68 |
|
| 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 |
| 71 |
|
| 72 |
Optionally, you can install a backup saveset with some programming examples, |
| 73 |
or a backupo saveset with the complete libssh2 source tree. |
| 74 |
|
| 75 |
you will need to answer 'NO' to the question |
| 76 |
'Do you want the default for all options'. |
| 77 |
|
| 78 |
and 'YES' to either or both the following questions: |
| 79 |
|
| 80 |
Do you want the libssh2 C programming examples ? [NO] |
| 81 |
|
| 82 |
Do you want the complete libssh2 source tree ? [NO] |
| 83 |
|
| 84 |
|
| 85 |
Post installation tasks |
| 86 |
----------------------- |
| 87 |
|
| 88 |
Although we will try to maintain upward compatibility of libssh2, |
| 89 |
this can not be guaranteed by the libssh2 project itself for OpenVMS, |
| 90 |
nor eternally by us. |
| 91 |
|
| 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: |
| 95 |
|
| 96 |
$ define/system/executive gnv$libssh2 dev:[dir..]gnv$libssh2_x_y_z.exe |
| 97 |
|
| 98 |
Optionally, you can install the executable like so: |
| 99 |
|
| 100 |
$ mc sysgen install dev:[dir..]gnv$libssh2_x_y_z.exe/open/share/header |
| 101 |
|
| 102 |
Link your programs against gnv$libssh2, and when upgrading libssh2 |
| 103 |
test thoroughly. |
| 104 |
|
| 105 |
If you want to be extra cautious define a system logical like this: |
| 106 |
|
| 107 |
$ define/system/executive gnv$libssh2_x_y_z dev:[dir..]gnv$libssh2_x_y_z.exe |
| 108 |
|
| 109 |
Link programs against gnv$libssh2_x_y_z, and when upgrading libssh2 |
| 110 |
link against new versions. |
| 111 |
|
| 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 |
| 115 |
are provided. |
| 116 |
|
| 117 |
|
| 118 |
Compiling and linking against libssh2 |
| 119 |
------------------------------------- |
| 120 |
|
| 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. |
| 124 |
|
| 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. |
| 127 |
|
| 128 |
If you chose to install the examples, you can unpack the backup |
| 129 |
saveset by |
| 130 |
|
| 131 |
backup/sel=*.c device:[gnv.usr.share.doc.libssh2.examples]libssh2_examples-x_y_z.bck - |
| 132 |
[] |
| 133 |
|
| 134 |
They can by compiled and linked by these commands ( provided you have defined |
| 135 |
the gnv$libssh2 logical) : |
| 136 |
|
| 137 |
$ cc/include=dev:[gnv.usr.include.libssh2] xxx.c/names=shortened |
| 138 |
$ link/opt=sys$input: xxx.obj |
| 139 |
gnv$libssh2/share |
| 140 |
|
| 141 |
|
| 142 |
|
| 143 |
|
| 144 |
Building gnv$libssh2 |
| 145 |
==================== |
| 146 |
|
| 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. |
| 149 |
|
| 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 |
| 153 |
issues. |
| 154 |
|
| 155 |
|
| 156 |
Prerequisites |
| 157 |
------------- |
| 158 |
|
| 159 |
You will need to have the following available: |
| 160 |
|
| 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. |
| 163 |
|
| 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. |
| 171 |
|
| 172 |
- TCP/IP services or Multinet for OpenVMS. |
| 173 |
TCPWare has not been tested. |
| 174 |
|
| 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. |
| 177 |
|
| 178 |
- A C compiler. I don't know any other working C compilers than |
| 179 |
the DEC/Compac/HP-C compiler on VMS. |
| 180 |
|
| 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. |
| 183 |
|
| 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 |
| 187 |
|
| 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 |
| 190 |
|
| 191 |
Optional: |
| 192 |
|
| 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. |
| 197 |
|
| 198 |
Downloading libssh2 |
| 199 |
------------------- |
| 200 |
|
| 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): |
| 206 |
|
| 207 |
$ libssh2_version = "1.2.6" |
| 208 |
$! |
| 209 |
$ proxy_line = " ""-U"" ""''proxy_userpass'"" ""-x"" ""''proxy_hostport'"" " |
| 210 |
$! |
| 211 |
$ currentday = f$cvtime(,,"date") - "-" - "-" |
| 212 |
$! |
| 213 |
$ set def mydev:[mydir.libssh2] |
| 214 |
$! |
| 215 |
$ if f$search("libssh2-''libssh2_version'-''currentday'.tar.gz") .nes. "" |
| 216 |
$ then |
| 217 |
$ delete libssh2-'libssh2_version'-'currentday'.tar.gz;* |
| 218 |
$ endif |
| 219 |
$! |
| 220 |
$ curl 'proxy_line' "https://libssh2.org/snapshots/libssh2-''libssh2_version'-''currentday'.tar.gz" - |
| 221 |
-o libssh2-'libssh2_version'-'currentday'.tar.gz |
| 222 |
$! |
| 223 |
$! |
| 224 |
$ if f$search("libssh2-''libssh2_version'-''currentday'.tar.;") .nes. "" |
| 225 |
$ then |
| 226 |
$ delete libssh2-'libssh2_version'-'currentday'.tar.;* |
| 227 |
$ endif |
| 228 |
$! |
| 229 |
$ gunzip libssh2-'libssh2_version'-'currentday'.tar.gz |
| 230 |
$! |
| 231 |
$ tarfile = f$search("libssh2-''libssh2_version'-''currentday'.tar.;") |
| 232 |
$ vmstar xf 'tarfile' |
| 233 |
|
| 234 |
Downloading a stable build will need you to get rid of the currentday. |
| 235 |
|
| 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. |
| 239 |
|
| 240 |
Getting the libssh2 sources from the source backup in the binary kit |
| 241 |
-------------------------------------------------------------------- |
| 242 |
|
| 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 |
| 246 |
[gnv.common_src]. |
| 247 |
|
| 248 |
By restoring this backup saveset, you end up with the same |
| 249 |
set of files as by the direct download from libssh2.org. |
| 250 |
|
| 251 |
|
| 252 |
Building the library |
| 253 |
-------------------- |
| 254 |
|
| 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 |
| 257 |
.dcl. |
| 258 |
|
| 259 |
Go to the vms subdirectory in the download tree, and issue the following |
| 260 |
command: |
| 261 |
|
| 262 |
@libssh2_make_lib.dcl |
| 263 |
|
| 264 |
This should produce libssh2_x_y_z.exe in this same vms directory. |
| 265 |
|
| 266 |
|
| 267 |
|
| 268 |
Building the examples |
| 269 |
--------------------- |
| 270 |
|
| 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. |
| 275 |
|
| 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 |
| 278 |
build procedure: |
| 279 |
|
| 280 |
@libssh2_make_example.dcl |
| 281 |
|
| 282 |
or for instance |
| 283 |
|
| 284 |
@libssh2_make_example.dcl sftp |
| 285 |
|
| 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: |
| 290 |
|
| 291 |
@libssh2_make_example.dcl sftp "SHARED" |
| 292 |
|
| 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. |
| 295 |
|
| 296 |
|
| 297 |
Building the help library |
| 298 |
------------------------- |
| 299 |
|
| 300 |
The man pages can be converted to a VMS help library by issuing |
| 301 |
this command : |
| 302 |
|
| 303 |
@libssh2_make_help.dcl |
| 304 |
|
| 305 |
It uses a simple but fairly effective c program man2help.c |
| 306 |
to achieve this. |
| 307 |
|
| 308 |
Building a PCSI kit |
| 309 |
------------------- |
| 310 |
|
| 311 |
When you have built the shared library and the help library, |
| 312 |
you can build a PCSI kit by issuing this command: |
| 313 |
|
| 314 |
@libssh2_make_kit.dcl |