The SSH channel functions
Overview
Functions that manage a SSH channel. More…
// structs struct ssh_channel_read_termination_struct; // global functions ssh_channel ssh_channel_new(ssh_session session); SSH_DEPRECATED LIBSSH_API int channel_read_buffer( ssh_channel channel, ssh_buffer buffer, uint32_t count, int is_stderr ); ssh_channel ssh_channel_accept_forward( ssh_session session, int timeout_ms, int* destination_port ); ssh_channel ssh_channel_accept_x11( ssh_channel channel, int timeout_ms ); int ssh_channel_cancel_forward( ssh_session session, const char* address, int port ); int ssh_channel_change_pty_size( ssh_channel channel, int cols, int rows ); int ssh_channel_close(ssh_channel channel); void ssh_channel_free(ssh_channel channel); int ssh_channel_get_exit_status(ssh_channel channel); ssh_session ssh_channel_get_session(ssh_channel channel); int ssh_channel_is_closed(ssh_channel channel); int ssh_channel_is_eof(ssh_channel channel); int ssh_channel_is_open(ssh_channel channel); int ssh_channel_listen_forward( ssh_session session, const char* address, int port, int* bound_port ); int ssh_channel_open_auth_agent(ssh_channel channel); int ssh_channel_open_forward( ssh_channel channel, const char* remotehost, int remoteport, const char* sourcehost, int localport ); int ssh_channel_open_session(ssh_channel channel); int ssh_channel_open_x11( ssh_channel channel, const char* orig_addr, int orig_port ); int ssh_channel_poll( ssh_channel channel, int is_stderr ); int ssh_channel_poll_timeout( ssh_channel channel, int timeout, int is_stderr ); int ssh_channel_read( ssh_channel channel, void* dest, uint32_t count, int is_stderr ); int ssh_channel_read_nonblocking( ssh_channel channel, void* dest, uint32_t count, int is_stderr ); int ssh_channel_read_timeout( ssh_channel channel, void* dest, uint32_t count, int is_stderr, int timeout_ms ); int ssh_channel_request_env( ssh_channel channel, const char* name, const char* value ); int ssh_channel_request_exec( ssh_channel channel, const char* cmd ); int ssh_channel_request_pty(ssh_channel channel); int ssh_channel_request_pty_size( ssh_channel channel, const char* term, int cols, int rows ); int ssh_channel_request_send_signal( ssh_channel channel, const char* signum ); int ssh_channel_request_shell(ssh_channel channel); int ssh_channel_request_subsystem( ssh_channel channel, const char* subsystem ); int ssh_channel_request_x11( ssh_channel channel, int single_connection, const char* protocol, const char* cookie, int screen_number ); int ssh_channel_select( ssh_channel* readchans, ssh_channel* writechans, ssh_channel* exceptchans, struct timeval* timeout ); int ssh_channel_send_eof(ssh_channel channel); void ssh_channel_set_blocking( ssh_channel channel, int blocking ); void ssh_channel_set_counter( ssh_channel channel, ssh_counter counter ); int ssh_channel_write( ssh_channel channel, const void* data, uint32_t len ); int channel_default_bufferize( ssh_channel channel, void* data, int len, int is_stderr ); static ssh_channel channel_from_msg( ssh_session session, ssh_buffer packet ); static int channel_open( ssh_channel channel, const char* type, int window, int maxpacket, ssh_buffer payload ); static int channel_protocol_select( ssh_channel* rchans, ssh_channel* wchans, ssh_channel* echans, ssh_channel* rout, ssh_channel* wout, ssh_channel* eout ); static int channel_request( ssh_channel channel, const char* request, ssh_buffer buffer, int reply ); static int channel_write_common( ssh_channel channel, const void* data, uint32_t len, int is_stderr ); static int count_ptrs(ssh_channel* ptrs); static char* generate_cookie(void); static int global_request( ssh_session session, const char* request, ssh_buffer buffer, int reply ); static int grow_window( ssh_session session, ssh_channel channel, int minimumsize ); static ssh_channel ssh_channel_accept( ssh_session session, int channeltype, int timeout_ms, int* destination_port ); void ssh_channel_do_free(ssh_channel channel); static int ssh_channel_exit_status_termination(void* c); int ssh_channel_flush(ssh_channel channel); ssh_channel ssh_channel_from_local( ssh_session session, uint32_t id ); uint32_t ssh_channel_new_id(ssh_session session); int ssh_channel_open_reverse_forward( ssh_channel channel, const char* remotehost, int remoteport, const char* sourcehost, int localport ); static int ssh_channel_open_termination(void* c); static int ssh_channel_read_termination(void* s); int ssh_channel_request_send_exit_signal( ssh_channel channel, const char* sig, int core, const char* errmsg, const char* lang ); int ssh_channel_request_send_exit_status( ssh_channel channel, int exit_status ); int ssh_channel_request_sftp(ssh_channel channel); static int ssh_channel_request_termination(void* c); static int ssh_channel_waitwindow_termination(void* c); uint32_t ssh_channel_window_size(ssh_channel channel); int ssh_channel_write_stderr( ssh_channel channel, const void* data, uint32_t len ); ssh_channel ssh_forward_accept( ssh_session session, int timeout_ms ); int ssh_forward_cancel( ssh_session session, const char* address, int port ); int ssh_forward_listen( ssh_session session, const char* address, int port, int* bound_port ); static int ssh_global_request_termination(void* s); SSH_PACKET_CALLBACK(ssh_packet_channel_open_conf); SSH_PACKET_CALLBACK(ssh_packet_channel_open_fail); SSH_PACKET_CALLBACK(channel_rcv_change_window); SSH_PACKET_CALLBACK(channel_rcv_data); SSH_PACKET_CALLBACK(channel_rcv_eof); SSH_PACKET_CALLBACK(channel_rcv_close); SSH_PACKET_CALLBACK(channel_rcv_request); SSH_PACKET_CALLBACK(ssh_packet_channel_success); SSH_PACKET_CALLBACK(ssh_packet_channel_failure); SSH_PACKET_CALLBACK(ssh_request_success); SSH_PACKET_CALLBACK(ssh_request_denied); static int ssh_waitsession_unblocked(void* s);
Detailed Documentation
Functions that manage a SSH channel.
Global Functions
ssh_channel ssh_channel_new(ssh_session session)
Allocate a new channel.
Parameters:
session |
The ssh session to use. |
Returns:
A pointer to a newly allocated channel, NULL on error.
SSH_DEPRECATED LIBSSH_API int channel_read_buffer( ssh_channel channel, ssh_buffer buffer, uint32_t count, int is_stderr )
Read data from a channel into a buffer.
Deprecated Please use ssh_channel_read instead
Warning
This function doesn’t work in nonblocking/timeout mode
Parameters:
channel |
The channel to read from. |
buffer |
The buffer which will get the data. |
count |
The count of bytes to be read. If it is bigger than 0, the exact size will be read, else (bytes=0) it will return once anything is available. |
is_stderr |
A boolean value to mark reading from the stderr stream. |
Returns:
The number of bytes read, 0 on end of file or SSH_ERROR on error.
See also:
ssh_channel ssh_channel_accept_forward( ssh_session session, int timeout_ms, int* destination_port )
Accept an incoming TCP/IP forwarding channel and get information about incomming connection.
Parameters:
session |
The ssh session to use. |
timeout_ms |
A timeout in milliseconds. |
destination_port |
A pointer to destination port or NULL. |
Returns:
Newly created channel, or NULL if no incoming channel request from the server
ssh_channel ssh_channel_accept_x11( ssh_channel channel, int timeout_ms )
Accept an X11 forwarding channel.
Parameters:
channel |
An x11-enabled session channel. |
timeout_ms |
Timeout in milliseconds. |
Returns:
A newly created channel, or NULL if no X11 request from the server.
int ssh_channel_cancel_forward( ssh_session session, const char* address, int port )
Sends the “cancel-tcpip-forward” global request to ask the server to cancel the tcpip-forward request.
Parameters:
session |
The ssh session to send the request. |
address |
The bound address on the server. |
port |
The bound port on the server. |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred, SSH_AGAIN if in nonblocking mode and call has to be done again.
int ssh_channel_change_pty_size( ssh_channel channel, int cols, int rows )
Change the size of the terminal associated to a channel.
Warning
Do not call it from a signal handler if you are not sure any other libssh function using the same channel/session is running at same time (not 100% threadsafe).
Parameters:
channel |
The channel to change the size. |
cols |
The new number of columns. |
rows |
The new number of rows. |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred.
int ssh_channel_close(ssh_channel channel)
Close a channel.
This sends an end of file and then closes the channel. You won’t be able to recover any data the server was going to send or was in buffers.
Parameters:
channel |
The channel to close. |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred.
See also:
void ssh_channel_free(ssh_channel channel)
Close and free a channel.
Warning
Any data unread on this channel will be lost.
Parameters:
channel |
The channel to free. |
int ssh_channel_get_exit_status(ssh_channel channel)
Get the exit status of the channel (error code from the executed instruction).
Warning
This function may block until a timeout (or never) if the other side is not willing to close the channel.
If you’re looking for an async handling of this register a callback for the exit status.
Parameters:
channel |
The channel to get the status from. |
Returns:
The exit status, -1 if no exit status has been returned (yet).
See also:
ssh_channel_exit_status_callback
ssh_session ssh_channel_get_session(ssh_channel channel)
Recover the session in which belongs a channel.
Parameters:
channel |
The channel to recover the session from. |
Returns:
The session pointer.
int ssh_channel_is_closed(ssh_channel channel)
Check if the channel is closed or not.
Parameters:
channel |
The channel to check. |
Returns:
0 if channel is opened, nonzero otherwise.
See also:
int ssh_channel_is_eof(ssh_channel channel)
Check if remote has sent an EOF.
Parameters:
channel |
The channel to check. |
Returns:
0 if there is no EOF, nonzero otherwise.
int ssh_channel_is_open(ssh_channel channel)
Check if the channel is open or not.
Parameters:
channel |
The channel to check. |
Returns:
0 if channel is closed, nonzero otherwise.
See also:
int ssh_channel_listen_forward( ssh_session session, const char* address, int port, int* bound_port )
Sends the “tcpip-forward” global request to ask the server to begin listening for inbound connections.
Parameters:
session |
The ssh session to send the request. |
address |
The address to bind to on the server. Pass NULL to bind to all available addresses on all protocol families supported by the server. |
port |
The port to bind to on the server. Pass 0 to ask the server to allocate the next available unprivileged port number |
bound_port |
The pointer to get actual bound port. Pass NULL to ignore. |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred, SSH_AGAIN if in nonblocking mode and call has to be done again.
int ssh_channel_open_auth_agent(ssh_channel channel)
Open an agent authentication forwarding channel.
This type of channel can be opened by a server towards a client in order to provide SSH-Agent services to the server-side process. This channel can only be opened if the client claimed support by sending a channel request beforehand.
Parameters:
channel |
An allocated channel. |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred, SSH_AGAIN if in nonblocking mode and call has to be done again.
See also:
int ssh_channel_open_forward( ssh_channel channel, const char* remotehost, int remoteport, const char* sourcehost, int localport )
Open a TCP/IP forwarding channel.
Warning
This function does not bind the local port and does not automatically forward the content of a socket to the channel. You still have to use channel_read and channel_write for this.
Parameters:
channel |
An allocated channel. |
remotehost |
The remote host to connected (host name or IP). |
remoteport |
The remote port. |
sourcehost |
The numeric IP address of the machine from where the connection request originates. This is mostly for logging purposes. |
localport |
The port on the host from where the connection originated. This is mostly for logging purposes. |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred, SSH_AGAIN if in nonblocking mode and call has to be done again.
int ssh_channel_open_session(ssh_channel channel)
Open a session channel (suited for a shell, not TCP forwarding).
Parameters:
channel |
An allocated channel. |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred, SSH_AGAIN if in nonblocking mode and call has to be done again.
See also:
int ssh_channel_open_x11( ssh_channel channel, const char* orig_addr, int orig_port )
Open a X11 channel.
Warning
This function does not bind the local port and does not automatically forward the content of a socket to the channel. You still have to use channel_read and channel_write for this.
Parameters:
channel |
An allocated channel. |
orig_addr |
The source host (the local server). |
orig_port |
The source port (the local server). |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred, SSH_AGAIN if in nonblocking mode and call has to be done again.
int ssh_channel_poll( ssh_channel channel, int is_stderr )
Polls a channel for data to read.
Warning
When the channel is in EOF state, the function returns SSH_EOF.
Parameters:
channel |
The channel to poll. |
is_stderr |
A boolean to select the stderr stream. |
Returns:
The number of bytes available for reading, 0 if nothing is available or SSH_ERROR on error.
See also:
int ssh_channel_poll_timeout( ssh_channel channel, int timeout, int is_stderr )
Polls a channel for data to read, waiting for a certain timeout.
Warning
When the channel is in EOF state, the function returns SSH_EOF.
Parameters:
channel |
The channel to poll. |
timeout |
Set an upper limit on the time for which this function will block, in milliseconds. Specifying a negative value means an infinite timeout. This parameter is passed to the poll() function. |
is_stderr |
A boolean to select the stderr stream. |
Returns:
The number of bytes available for reading, 0 if nothing is available (timeout elapsed), SSH_EOF on end of file, SSH_ERROR on error.
See also:
int ssh_channel_read( ssh_channel channel, void* dest, uint32_t count, int is_stderr )
Reads data from a channel.
Warning
This function may return less than count bytes of data, and won’t block until count bytes have been read.
Warning
The read function using a buffer has been renamed to channel_read_buffer().
Parameters:
channel |
The channel to read from. |
dest |
The destination buffer which will get the data. |
count |
The count of bytes to be read. |
is_stderr |
A boolean value to mark reading from the stderr flow. |
Returns:
The number of bytes read, 0 on end of file or SSH_ERROR on error. In nonblocking mode it Can return 0 if no data is available or SSH_AGAIN.
int ssh_channel_read_nonblocking( ssh_channel channel, void* dest, uint32_t count, int is_stderr )
Do a nonblocking read on the channel.
A nonblocking read on the specified channel. it will return <= count bytes of data read atomically.
Warning
Don’t forget to check for EOF as it would return 0 here.
Parameters:
channel |
The channel to read from. |
dest |
A pointer to a destination buffer. |
count |
The count of bytes of data to be read. |
is_stderr |
A boolean to select the stderr stream. |
Returns:
The number of bytes read, 0 if nothing is available or SSH_ERROR on error.
See also:
int ssh_channel_read_timeout( ssh_channel channel, void* dest, uint32_t count, int is_stderr, int timeout_ms )
Reads data from a channel.
Warning
This function may return less than count bytes of data, and won’t block until count bytes have been read.
Warning
The read function using a buffer has been renamed to channel_read_buffer().
Parameters:
channel |
The channel to read from. |
dest |
The destination buffer which will get the data. |
count |
The count of bytes to be read. |
is_stderr |
A boolean value to mark reading from the stderr flow. |
timeout_ms |
A timeout in milliseconds. A value of -1 means infinite timeout. |
Returns:
The number of bytes read, 0 on end of file or SSH_ERROR on error. In nonblocking mode it Can return 0 if no data is available or SSH_AGAIN.
int ssh_channel_request_env( ssh_channel channel, const char* name, const char* value )
Set environment variables.
Warning
Some environment variables may be refused by security reasons.
Parameters:
channel |
The channel to set the environment variables. |
name |
The name of the variable. |
value |
The value to set. |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred, SSH_AGAIN if in nonblocking mode and call has to be done again.
int ssh_channel_request_exec( ssh_channel channel, const char* cmd )
Run a shell command without an interactive shell.
This is similar to ‘sh -c command’.
Example:
rc = channel_request_exec(channel, "ps aux"); if (rc > 0) { return -1; } while ((rc = channel_read(channel, buffer, sizeof(buffer), 0)) > 0) { if (fwrite(buffer, 1, rc, stdout) != (unsigned int) rc) { return -1; } }
Parameters:
channel |
The channel to execute the command. |
cmd |
The command to execute (e.g. “ls ~/ -al | grep -i reports”). |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred, SSH_AGAIN if in nonblocking mode and call has to be done again.
See also:
int ssh_channel_request_pty(ssh_channel channel)
Request a PTY.
Parameters:
channel |
The channel to send the request. |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred, SSH_AGAIN if in nonblocking mode and call has to be done again.
See also:
ssh_channel_request_pty_size()
int ssh_channel_request_pty_size( ssh_channel channel, const char* term, int cols, int rows )
Request a pty with a specific type and size.
Parameters:
channel |
The channel to sent the request. |
terminal |
The terminal type (“vt100, xterm,…”). |
col |
The number of columns. |
row |
The number of rows. |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred, SSH_AGAIN if in nonblocking mode and call has to be done again.
int ssh_channel_request_send_signal( ssh_channel channel, const char* signum )
Send a signal to remote process (as described in RFC 4254, section 6.9).
Sends a signal ‘sig’ to the remote process. Note, that remote system may not support signals concept. In such a case this request will be silently ignored. Only SSH-v2 is supported (I’m not sure about SSH-v1).
OpenSSH doesn’t support signals yet, see: https://bugzilla.mindrot.org/show_bug.cgi?id=1424
Parameters:
channel |
The channel to send signal. |
sig |
The signal to send (without SIG prefix) SIGABRT -> ABRT SIGALRM -> ALRM SIGFPE -> FPE SIGHUP -> HUP SIGILL -> ILL SIGINT -> INT SIGKILL -> KILL SIGPIPE -> PIPE SIGQUIT -> QUIT SIGSEGV -> SEGV SIGTERM -> TERM SIGUSR1 -> USR1 SIGUSR2 -> USR2 |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred (including attempts to send signal via SSH-v1 session).
int ssh_channel_request_shell(ssh_channel channel)
Request a shell.
Parameters:
channel |
The channel to send the request. |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred, SSH_AGAIN if in nonblocking mode and call has to be done again.
int ssh_channel_request_subsystem( ssh_channel channel, const char* subsystem )
Request a subsystem (for example “sftp”).
Warning
You normally don’t have to call it for sftp, see sftp_new().
Parameters:
channel |
The channel to send the request. |
subsys |
The subsystem to request (for example “sftp”). |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred, SSH_AGAIN if in nonblocking mode and call has to be done again.
int ssh_channel_request_x11( ssh_channel channel, int single_connection, const char* protocol, const char* cookie, int screen_number )
Sends the “x11-req” channel request over an existing session channel.
This will enable redirecting the display of the remote X11 applications to local X server over an secure tunnel.
Parameters:
channel |
An existing session channel where the remote X11 applications are going to be executed. |
single_connection |
A boolean to mark only one X11 app will be redirected. |
protocol |
A x11 authentication protocol. Pass NULL to use the default value MIT-MAGIC-COOKIE-1. |
cookie |
A x11 authentication cookie. Pass NULL to generate a random cookie. |
screen_number |
The screen number. |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred, SSH_AGAIN if in nonblocking mode and call has to be done again.
int ssh_channel_select( ssh_channel* readchans, ssh_channel* writechans, ssh_channel* exceptchans, struct timeval* timeout )
Act like the standard select(2) on channels.
The list of pointers are then actualized and will only contain pointers to channels that are respectively readable, writable or have an exception to trap.
Parameters:
readchans |
A NULL pointer or an array of channel pointers, terminated by a NULL. |
writechans |
A NULL pointer or an array of channel pointers, terminated by a NULL. |
exceptchans |
A NULL pointer or an array of channel pointers, terminated by a NULL. |
timeout |
Timeout as defined by select(2). |
Returns:
SSH_OK on a successful operation, SSH_EINTR if the select(2) syscall was interrupted, then relaunch the function.
int ssh_channel_send_eof(ssh_channel channel)
Send an end of file on the channel.
This doesn’t close the channel. You may still read from it but not write.
Example:
rc = ssh_channel_send_eof(channel); if (rc == SSH_ERROR) { return -1; } while(!ssh_channel_is_eof(channel)) { rc = ssh_channel_read(channel, buf, sizeof(buf), 0); if (rc == SSH_ERROR) { return -1; } } ssh_channel_close(channel);
Parameters:
channel |
The channel to send the eof to. |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred.
See also:
void ssh_channel_set_blocking( ssh_channel channel, int blocking )
Put the channel into blocking or nonblocking mode.
Warning
A side-effect of this is to put the whole session in non-blocking mode.
Parameters:
channel |
The channel to use. |
blocking |
A boolean for blocking or nonblocking. |
See also:
void ssh_channel_set_counter( ssh_channel channel, ssh_counter counter )
Set the channel data counter.
struct ssh_counter_struct counter = { .in_bytes = 0, .out_bytes = 0, .in_packets = 0, .out_packets = 0 }; ssh_channel_set_counter(channel, &counter);
Parameters:
channel |
The SSH channel. |
counter |
Counter for bytes handled by the channel. |
int ssh_channel_write( ssh_channel channel, const void* data, uint32_t len )
Blocking write on a channel.
Parameters:
channel |
The channel to write to. |
data |
A pointer to the data to write. |
len |
The length of the buffer to write to. |
Returns:
The number of bytes written, SSH_ERROR on error.
See also:
int ssh_channel_open_reverse_forward( ssh_channel channel, const char* remotehost, int remoteport, const char* sourcehost, int localport )
Open a TCP/IP reverse forwarding channel.
Warning
This function does not bind the local port and does not automatically forward the content of a socket to the channel. You still have to use channel_read and channel_write for this.
Parameters:
channel |
An allocated channel. |
remotehost |
The remote host to connected (host name or IP). |
remoteport |
The remote port. |
sourcehost |
The source host (your local computer). It’s optional and for logging purpose. |
localport |
The source port (your local computer). It’s optional and for logging purpose. |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred, SSH_AGAIN if in nonblocking mode and call has to be done again.
int ssh_channel_request_send_exit_signal( ssh_channel channel, const char* sig, int core, const char* errmsg, const char* lang )
Send an exit signal to remote process (RFC 4254, section 6.10).
This sends the exit status of the remote process. Note, that remote system may not support signals concept. In such a case this request will be silently ignored. Only SSH-v2 is supported (I’m not sure about SSH-v1).
Parameters:
channel |
The channel to send signal. |
sig |
The signal to send (without SIG prefix) (e.g. “TERM” or “KILL”). |
core |
A boolean to tell if a core was dumped |
errmsg |
A CRLF explanation text about the error condition |
lang |
The language used in the message (format: RFC 3066) |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred (including attempts to send signal via SSH-v1 session).
int ssh_channel_request_send_exit_status( ssh_channel channel, int exit_status )
Send the exit status to the remote process.
Sends the exit status to the remote process (as described in RFC 4254, section 6.10). Only SSH-v2 is supported (I’m not sure about SSH-v1).
Parameters:
channel |
The channel to send exit status. |
exit_status |
The exit status to send |
Returns:
SSH_OK on success, SSH_ERROR if an error occurred. (including attempts to send exit status via SSH-v1 session).
int ssh_channel_write_stderr( ssh_channel channel, const void* data, uint32_t len )
Blocking write on a channel stderr.
Parameters:
channel |
The channel to write to. |
data |
A pointer to the data to write. |
len |
The length of the buffer to write to. |
Returns:
The number of bytes written, SSH_ERROR on error.
See also: