Frequently Asked Questions
- What is libssh2?
- What tasks can libssh2 be used for?
- Can I type commands via libssh2 and see what's happening?
- What is the SSH-2 protocol?
- How can I get started using libssh2?
- An example does not work for me!
- Where can I find more help?
- My application doesn't work, I think there is a problem with libssh2!
- How can I debug my libssh2 application?
- libssh2 is great, can I help out?
What is libssh2?
Simply put, libssh2 is a open-source software library intended to allow software developers access to the SSH-2 protocol in an easy-to-use self-contained package and is developed by individuals who contribute their free time to the project. It can be built into an application to perform many different tasks when communicating with a server that supports the SSH-2 protocol.
What tasks can libssh2 be used for?
Most commonly, libssh2 can be used to permit file transfer using SCP or SFTP, to communicate with a program that runs on the remote host, or to tunnel TCP connections through the secure transport offered by SSH.
Can I type commands via libssh2 and see what's happening?
No - libssh2 is a software library, meaning it supports the application developer. It allows communication using only the SSH-2 protocol, no added bells or whistles on top of the protocol, and your application is responsible for handling the content that is sent and received using libssh2. If you want to create an interactive connection to a server you need a terminal emulator, such as PuTTY (Windows), Terminal.app (Mac OS X) or xterm (UNIX/Linux) together with OpenSSH where available.
What is the SSH-2 protocol?
It is a means for secure communication (authorization, encryption and authentication) between a compliant server and client, on top of TCP. The protocol itself is too complex to describe here, and in fact the library is intended to abstract many protocol details away from the software developer. Please see the Wikipedia article on SSH for more detail on the protocol along with links to the IETF RFC documents that is the formal protocol description. The most common RFCs are:
- RFC 4250 SSH Protocol Assigned Numbers
- RFC 4251 SSH Protocol Architecture
- RFC 4252 SSH Authentication Protocol
- RFC 4253 SSH Transport Layer Protocol
- RFC 4254 SSH Connection Protocol
- RFC 4256 Generic Message Exchange for SSH Authentication AKA keyboard-interactive
How can I get started using libssh2?
An example does not work for me!
This is possibly more common that you realise. Many of our examples are written with assumptions about usernames and passwords, and further assume that the server they connect to actually wants to talk to them. Before you get the blamethrower out, please take a moment to find out if you can connect to the same server using another SSH client, like PuTTY or OpenSSH (the ssh command, depending on your client system).
If you find that another client works, but the example still doesn't work, please mention that you've tried this when asking for help. More often than not, the server is expecting keyboard-interactive authentication, and the example uses password authentication. Time to check the documentation! See also the link to RFC 4256 above.
Where can I find more help?
We have a mailing list (with archives) as well as the #libssh2 IRC channel on freenode. Please check to see if your question has already been answered, and don't be offended if we point you to this FAQ!
My application doesn't work, I think there is a problem with libssh2!
You can create a ticket here on Trac, providing clear details on what you're trying to do and how we might reproduce your problem. As always, please try to reproduce the problem using the latest released version of the library or even better current source from the git repository - we still receive faults reported against old versions just because they've been packaged with a particular Linux distribution, and those bugs have long since been fixed.
If your problem is not with libssh2 itself, please don't demand an answer unless you are planning to pay someone to support you. That said, if you stumble over a new problem we haven't seen before, we're interested in knowing about it so that we can make the library better for everyone.
How can I debug my libssh2 application?
As this point you're almost certainly more experienced with using the library, and it's time to point you to one of the built-in diagnostics: tracing. You'll need a version of the library which was built to include trace messages (configure --enable-debug) and you then call the function that enables debug output: libssh2_trace(). If you want to have the messages go somewhere other than stderr, check out libssh2_trace_sethandler(). Armed with these two functions, you can provide protocol diagnostics that can be attached to a Trac ticket that let the maintainers know exactly what's happening and allow them to work with you to hunt down and exterminate your bug, whether it's a problem in the library or in the particular way you end up using it.
libssh2 is great, can I help out?
By all means! Whether it's a change to the library or the website, we'd love to hear from you.
If you have something you would like to see added to the library, you can send it to the mailing list, ideally as a patch (see the Development page) created by the git format-patch command or sent by the git send-email command, or you can attach the patch to a Trac ticket along with a brief explanation and we'll take it from there - although please be prepared for us to discuss it if we think the patch should be changed, e.g. if it breaks some existing functionality. Discussions can sometimes take a long time on hot topics like this, but if it's something we like then it can be incorporated quite quickly. Who knows, you may even get mentioned as contributing to the next release!
On the other hand, if you would like to help out with the website or the Trac wiki, whether it's by adding some documentation that might help others or if you've spotted a problem on the website, please let us know. If in doubt, just send a mail to the mailing list, or pop onto IRC and ask someone - we won't bite!