| *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 |
| |
| |
| |
| |
| |