Skip to content

Latest commit

 

History

History
163 lines (119 loc) · 9.58 KB

README.md

File metadata and controls

163 lines (119 loc) · 9.58 KB
Raw

Contributors Forks Stargazers Issues Build Status BSD-3-Clause License


Logo

lvssh2

LabVIEW™ bindings for libssh2.
Explore the docs »

View Demo
Report Bug
Request Feature

About The Project

lvssh2 provides LabVIEW™ bindings for libssh2.

See libssh2-api for API coverage.

Limitations

Note

There is currently no built-in support for Linux and macOS. Users need to build the libssh2 shared library for these platforms themselves.

Although this project aims to provide complete bindings for libssh2, there are several limitations users need to be aware of:

  • Buffer sizes are limited to 2^31-1 bytes (2 GiB) instead of 2^32-1 bytes (4 GiB). The reason for this is that arrays and strings in LabVIEW are limited to 2^31-1 elements. Additional limits may apply due to memory copies when calling external functions.
  • This project includes an extension library to provide functionality that cannot otherwise be realized in LabVIEW. Callers can specify a conditional disable symbol LVSSH2_NO_EXTENSIONS=True to disable the extension library. When this conditional disable symbol is set, then all functions utilizing the extension library will turn into stubs.
  • The public key subsystem is currently not implemented because of lack of support in OpenSSH and other major SSH servers. You can find more information at ssh-publickeyd.

Design Decisions

  • Thread Safety: This project uses semaphores to ensure thread safety on a session level. This means that all functions on a session (including channels, subsystems, etc.) execute mutually exclusive (with few exceptions). This is done to ensure that the underlying libssh2 session (and by extension the underlying TCP connection) is not accessed concurrently, which could result in memory corruption and undefined behaviour. Note that this does not prevent callers from using multiple sessions concurrently. For example, a caller could use one session to execute a command and another session to transfer files without interering with each other.
  • Error Handling: This project uses the LabVIEW error handling mechanism. All functions return an error cluster that corresponds to a libssh2 error code (see lvssh2-errors.txt and lvssh2-sftp-errors.txt). See libssh2-api for a complete overview of error codes and how they are defined.
  • Length Parameters for String and Array types: All functions that take a string or array type as an input parameter do not expose a separate length parameter. Instead, the length of the string or array is determined by the type itself. Because of this, some of the libssh2 convenience functions are not included. For example, libssh2_channel_window_write is not included because it would be equivalent to libssh2_channel_window_write_ex. For a complete overview of the functions that are included, see libssh2-api.
  • Pointer Handling: Pointers are not exposed to the caller. Instead, the caller receives a Refnum that represents a Data Value Reference which contains the pointer. This is done to provide a more LabVIEW-like interface and to avoid pointer handling for the caller. Note that this also ensures 32-bit and 64-bit compatibility.
  • Constants: Constants are defined as enum typedefs in the lvssh2 library. This is done to provide a more LabVIEW-like interface. See libssh2-api for a complete overview of the constants and how they are defined.
  • Naming Conventions: The naming conventions for functions are based on the libssh2 function names. VI titles contain a human-readable function name and the function name of libssh2 in parenthesis. For example, the title for libssh2_agent_get_identity is "SSH Agent Get Identity (libssh2_agent_get_identity)". This makes it easier to find functions in quick-drop.

Note

VI titles and descriptions are defined in lvssh2-descriptions.xml using Update Descriptions.vi. This is done to allow for easy updating of the descriptions using modern text editors (e.g., with Copilot support).

Built With

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites

Installation

  1. Clone the repo

    git clone https://github.com/logmanoriginal/lvssh2.git

Build Instructions

Usage

Here is an example that uses lvssh2 to execute a command on a remote SSH server.

Example

Roadmap

See the open issues for a list of proposed features (and known issues).

Further Reading

  • RFC4251: The Secure Shell (SSH) Protocol Architecture
  • RFC4252: The Secure Shell (SSH) Authentication Protocol
  • RFC4253: The Secure Shell (SSH) Transport Layer Protocol
  • RFC4254: The Secure Shell (SSH) Connection Protocol
  • RFC4819: Secure Shell Public Key Subsystem

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Keep in mind that LabVIEW™ VIs are binary files, which are difficult to merge.

  • Only change a single VI or library.
  • Avoid conflicts with other pull requests (don't work on the same libraries or VIs).
  • Send VI Snippets (via issues) instead of pull requests when possible.

Note

This project contains C++ code that is compiled into a shared library (see extensions). If you are familiar with C++ and want to contribute to the project, please consider contributing to the C++ code as well.

License

Distributed under the BSD-3-Clause License. See LICENSE for more information.

This project uses third-party libraries or other resources that may be distributed under different licenses. See THIRD-PARTY-NOTICES for more information.

Contact

Project Link: https://github.com/logmanoriginal/lvssh2

Acknowledgements