*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 executable 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 whether 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 issuing this command: @libssh2_make_kit.dcl