Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ssh_connection(3)	   Erlang Module Definition	     ssh_connection(3)

NAME
       ssh_connection  -  This module provides API functions to	send  SSH Con-
       nection Protocol
	 events	to the other side of an	SSH channel.

DESCRIPTION
       The SSH Connection Protocol is used by clients and  servers  (i.e.  SSH
       channels)  to communicate over the SSH connection. The API functions in
       this module sends SSH Connection	Protocol events	that are  received  as
       messages	 by the	remote channel.	In the case that the receiving channel
       is an Erlang process the	 message  will	be  on	the  following	format
       {ssh_cm,	ssh_connection_ref(), ssh_event_msg()}.	If the ssh_channel be-
       havior is used to implement the channel process these will  be  handled
       by handle_ssh_msg/2 .

DATA TYPES
       Type definitions	that are used more than	once in	this module and/or ab-
       stractions to indicate the intended use of the data type:

       boolean() = true	| false

       string()	= list of ASCII	characters

       timeout() = infinity | integer()	- in milliseconds.

       ssh_connection_ref() - opaque to	the user returned by ssh:connect/3  or
       sent to an SSH channel processes

       ssh_channel_id()	= integer()

       ssh_data_type_code()  = 1 ("stderr") | 0	("normal") are currently valid
       values see RFC 4254  section 5.2.

       ssh_request_status() = success |	failure

       event() = {ssh_cm, ssh_connection_ref(),	ssh_event_msg()}

       ssh_event_msg() = data_events() | status_events() | terminal_events()

       reason()	= timeout | closed

	 data_events() :

	   {data, ssh_channel_id(), ssh_data_type_code(), binary() = Data}:
	      Data has arrived on the channel. This event is sent as result of
	     calling  ssh_connection:send/[3,4,5]

	   {eof, ssh_channel_id()}:
	     Indicates	that  the other	side will not send any more data. This
	     event is sent as result of	calling	 ssh_connection:send_eof/2

	 status_events() :

	   {signal, ssh_channel_id(), ssh_signal()}:
	     A signal can be delivered to the remote process/service using the
	     following	message.  Some	systems	 will  not support signals, in
	     which case	they should ignore this	message. There is currently no
	     funtion  to  generate this	event as the signals refered to	are on
	     OS-level and not something	generated by an	Erlang program.

	   {exit_signal, ssh_channel_id(), string() = ExitSignal,  string()  =
	   ErrorMsg, string() =	LanguageString}:
	     A	remote	execution may terminate	violently due to a signal then
	     this message may be received. For details on valid	string	values
	     see  RFC 4254 section 6.10. Special case of the signals mentioned
	     above.

	   {exit_status, ssh_channel_id(), integer() = ExitStatus}:
	      When the command running at the other end	terminates,  the  fol-
	     lowing  message can be sent to return the exit status of the com-
	     mand. A zero 'exit_status'	usually	means that the command	termi-
	     nated  successfully.  This	 event	is  sent  as result of calling
	     ssh_connection:exit_status/3

	   {closed, ssh_channel_id()}:
	      This event is sent as result of  calling	ssh_connection:close/2
	     Both  the	handling of this event and sending of it will be taken
	     care of by	the ssh_channel	behavior.

	 terminal_events() :
	   Channels implementing a shell and command execution on  the	server
	   side	 should	 handle	 the  following	 messages  that	may be sent by
	   client channel processes.

     Note:
	 Events	that includes a	 WantReply expects the event handling  process
	 to  call  ssh_connection:reply_request/4  with	 the  boolean value of
	 WantReply as the second argument.

	   {env, ssh_channel_id(), boolean()  =	 WantReply,  string()  =  Var,
	   string() = Value}:
	      Environment  variables  may be passed to the shell/command to be
	     started later. This event is sent as result of calling   ssh_con-
	     nection:setenv/5

	   {pty,  ssh_channel_id(),  boolean() = WantReply, {string() =	Termi-
	   nal,	integer() = CharWidth, integer() = RowHeight, integer()	= Pix-
	   elWidth,  integer()	=  PixelHeight,	[{atom() | integer() = Opcode,
	   integer() = Value}] = TerminalModes}}:
	     A pseudo-terminal has been	requested for the session. Terminal is
	     the  value	 of the	TERM environment variable value	(e.g., vt100).
	     Zero dimension parameters must be ignored.	The character/row  di-
	     mensions  override	the pixel dimensions (when nonzero). Pixel di-
	     mensions refer to the drawable area of the	window.	The Opcode  in
	     the  TerminalModes	 list  is the mnemonic name, represented as an
	     lowercase erlang atom, defined in RFC 4254	  section  8.  It  may
	     also  be an opcode	if the mnemonic	name is	not listed in the RFC.
	     Example OP	code: 53, mnemonic name	ECHO  erlang  atom:  echo.This
	     event is sent as result of	calling	ssh_connection:ptty_alloc/4

	   {shell, boolean() = WantReply}:
	      This  message  will  request  that  the  user's default shell be
	     started at	the other end. This event is sent as result of calling
	     ssh_connection:shell/2

	   {window_change,  ssh_channel_id(), integer()	= CharWidth, integer()
	   = RowHeight,	integer() = PixWidth, integer()	= PixHeight}:
	      When the window (terminal) size changes on the client  side,  it
	     MAY send a	message	to the server side to inform it	of the new di-
	     mensions. There is	currently no API  function  to	generate  this
	     event.

	   {exec, ssh_channel_id(), boolean() =	WantReply, string() = Cmd}:
	      This  message  will  request that	the server starts execution of
	     the given command.	This  event  is	 sent  as  result  of  calling
	     ssh_connection:exec/4

EXPORTS
       adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok

	      Types:

		  ConnectionRef	= ssh_connection_ref()
		  ChannelId = ssh_channel_id()
		  NumOfBytes = integer()

	      Adjusts  the  SSH	flowcontrol window. This shall be done by both
	      client and server	side channel processes.

	  Note:
	      Channels implemented with	the  ssh_channel behavior will normaly
	      not  need	 to call this function as flow control will be handled
	      by the behavior. The behavior will adjust	the window every  time
	      the  callback   handle_ssh_msg/2	 has returned after processing
	      channel data

       close(ConnectionRef, ChannelId) -> ok

	      Types:

		  ConnectionRef	= ssh_connection_ref()
		  ChannelId = ssh_channel_id()

	      A	server or client channel process can  choose  to  close	 their
	      session by sending a close event.

	  Note:
	      This  function  will  be called by the ssh_channel behavior when
	      the channel is terminated	see  ssh_channel(3)  so	 channels  im-
	      plemented	 with  the  behavior should not	call this function ex-
	      plicitly.

       exec(ConnectionRef, ChannelId, Command,	TimeOut)  ->  ssh_request_sta-
       tus() | {error, reason()}

	      Types:

		  ConnectionRef	= ssh_connection_ref()
		  ChannelId = ssh_channel_id()
		  Command = string()
		 Timeout = timeout()

	      Should be	called by a client channel process to request that the
	      server starts execution of the given command, the	result will be
	      several  messages	 according to the following pattern. Note that
	      the last message will be a channel close message,	 as  the  exec
	      request  is a one	time execution that closes the channel when it
	      is done.

		 N x {ssh_cm, ssh_connection_ref(),  {data,  ssh_channel_id(),
		ssh_data_type_code(), binary() = Data}}	:
		  The  result of executing the command may be only one line or
		  thousands of lines depending on the command.

		0  or  1  x  {ssh_cm,  ssh_connection_ref(),  {eof,  ssh_chan-
		nel_id()}}:
		  Indicates that no more data will be sent.

		0   or	 1   x	{ssh_cm,  ssh_connection_ref(),	 {exit_signal,
		ssh_channel_id(), string() = ExitSignal, string() =  ErrorMsg,
		string() = LanguageString}}:
		  Not  all  systems  send signals. For details on valid	string
		  values see RFC 4254 section 6.10

		0  or  1  x   {ssh_cm,	 ssh_connection_ref(),	 {exit_status,
		ssh_channel_id(), integer() = ExitStatus}}:
		  It  is  recommended by the ssh connection protocol that this
		  message shall	be sent, but that may not always be the	case.

		 1  x  {ssh_cm,	  ssh_connection_ref(),	  {closed,   ssh_chan-
		nel_id()}}:
		  Indicates  that the ssh channel started for the execution of
		  the command has now been shutdown.

       exit_status(ConnectionRef, ChannelId, Status) ->	ok

	      Types:

		  ConnectionRef	= ssh_connection_ref()
		  ChannelId = ssh_channel_id()
		  Status = integer()

	      Should be	called by a server channel process to sends  the  exit
	      status of	a command to the client.

       ptty_alloc(ConnectionRef, ChannelId, Options) ->
       ptty_alloc(ConnectionRef,  ChannelId,  Options,	Timeout)  -> > ssh_re-
       quest_status() |	{error,	reason()}

	      Types:

		  ConnectionRef	= ssh_connection_ref()
		  ChannelId = ssh_channel_id()
		  Options = proplists:proplist()

	      Sends a SSH Connection Protocol pty_req, to  allocate  a	pseudo
	      tty. Should be called by a SSH client process. Options are:

		{term, string()}:
		   Defaults  to	 os:getenv("TERM")  or	"vt100"	if it is unde-
		  fined.

		{width,	integer()}:
		   Defaults to 80 if pixel_width is not	defined.

		{height, integer()}:
		   Defaults to 24 if pixel_height is not defined.

		{pixel_width, integer()}:
		   Is disregarded if width is defined.

		{pixel_height, integer()}:
		   Is disregarded if height is defined.

		{pty_opts, [{posix_atom(), integer()}]}:
		   Option may be an empty list,	otherwise see  possible	 POSIX
		  names	in section 8 in	 RFC 4254.

       reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok

	      Types:

		  ConnectionRef	= ssh_connection_ref()
		  WantReply = boolean()
		  Status = ssh_request_status()
		  ChannelId = ssh_channel_id()

	      Sends  status replies to requests	where the requester has	stated
	      that they	want a status  report  e.i  .  WantReply  =  true,  if
	      WantReply	 is  false  calling  this  function  will be a "noop".
	      Should be	called while handling an ssh connection	protocol  mes-
	      sage containing a	WantReply boolean value.

       send(ConnectionRef, ChannelId, Data) ->
       send(ConnectionRef, ChannelId, Data, Timeout) ->
       send(ConnectionRef, ChannelId, Type, Data) ->
       send(ConnectionRef,  ChannelId,	Type,  Data,  TimeOut) -> ok | {error,
       timeout}	| {error, closed}

	      Types:

		  ConnectionRef	= ssh_connection_ref()
		  ChannelId = ssh_channel_id()
		  Data = binary()
		  Type = ssh_data_type_code()
		  Timeout = timeout()

	      Should be	called by client- and server channel processes to send
	      data to each other.

       send_eof(ConnectionRef, ChannelId) -> ok	| {error, closed}

	      Types:

		  ConnectionRef	= ssh_connection_ref()
		  ChannelId = ssh_channel_id()

	      Sends eof	on the channel ChannelId.

       session_channel(ConnectionRef, Timeout) ->
       session_channel(ConnectionRef,  InitialWindowSize, MaxPacketSize, Time-
       out) -> {ok, ssh_channel_id()} |	{error,	reason()}

	      Types:

		  ConnectionRef	= ssh_connection_ref()
		  InitialWindowSize = integer()
		  MaxPacketSize	= integer()
		  Timeout = timeout()
		  Reason = term()

	      Opens a channel for an SSH session. The channel id returned from
	      this  function  is the id	used as	input to the other funtions in
	      this module.

       setenv(ConnectionRef,  ChannelId,  Var,	Value,	TimeOut)  ->   ssh_re-
       quest_status() |	{error,	reason()}

	      Types:

		  ConnectionRef	= ssh_connection_ref()
		  ChannelId = ssh_channel_id()
		  Var =	string()
		  Value	= string()
		  Timeout = timeout()

	      Environment   variables	may  be	 passed	 before	 starting  the
	      shell/command. Should be called by a client channel processes.

       shell(ConnectionRef,  ChannelId)	 ->  ssh_request_status()  |   {error,
       closed}

	      Types:

		  ConnectionRef	= ssh_connection_ref()
		  ChannelId = ssh_channel_id()

	      Should be	called by a client channel process to request that the
	      user's default shell (typically defined in /etc/passwd  in  UNIX
	      systems) shall be	executed at the	server end.

       subsystem(ConnectionRef,	 ChannelId,  Subsystem,	 Timeout)  ->  ssh_re-
       quest_status() |	{error,	reason()}

	      Types:

		  ConnectionRef	= ssh_connection_ref()
		  ChannelId = ssh_channel_id()
		  Subsystem = string()
		  Timeout = timeout()

	      Should be	called by a client channel process for	requesting  to
	      execute a	predefined subsystem on	the server.

Ericsson AB			    ssh	3.2		     ssh_connection(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ssh_connection&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help