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 Connection Protocol
	   events to the other side of an SSH channel.

DESCRIPTION
       The  SSH	 Connection  Protocol is used by clients and servers, that is,
       SSH channels, to	communicate over the SSH connection. The API functions
       in  this	module send SSH	Connection Protocol events, which are received
       as messages by the remote channel. If the receiving channel is  an  Er-
       lang  process,  the messages have the format {ssh_cm, connection_ref(),
       ssh_event_msg()}. If the	ssh_client_channel behavior is used to	imple-
       ment   the   channel  process,  these  messages	are  handled  by  han-
       dle_ssh_msg/2.

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

	 boolean() =:
	   true	| false

	 string() =:
	   list	of ASCII characters

	 timeout() =:
	   infinity | integer()	in milliseconds

	 connection_ref() =:
	   opaque()  -as  returned  by ssh:connect/3 or	sent to	an SSH channel
	   processes

	 channel_id() =:
	   integer()

	 ssh_data_type_code() =:
	   1 ("stderr")	| 0 ("normal") are valid values, see RFC 4254  Section
	   5.2.

	 ssh_request_status() =:
	   success | failure

	 event() =:
	   {ssh_cm, connection_ref(), ssh_event_msg()}

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

	 reason() =:
	   timeout | closed

	 data_events():

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

	   {eof, channel_id()}:
	     Indicates that the	other side sends no more data. This  event  is
	     sent as a result of calling  ssh_connection:send_eof/2.

	 status_events():

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

	   {exit_signal,   channel_id(),   ExitSignal  ::  string(),  ErrorMsg
	   ::string(), LanguageString :: string()}:
	     A remote execution	can terminate violently	because	of  a  signal.
	     Then  this	 message  can be received. For details on valid	string
	     values, see RFC 4254 Section 6.10,	which shows a special case  of
	     these signals.

	   {exit_status, channel_id(), ExitStatus :: integer()}:
	     When the command running at the other end terminates, the follow-
	     ing message can be	sent to	return the exit	status of the command.
	     A zero exit_status	usually	means that the command terminated suc-
	     cessfully.	This event is sent as a	result of calling  ssh_connec-
	     tion:exit_status/3.

	   {closed, channel_id()}:
	     This event	is sent	as a result of calling ssh_connection:close/2.
	     Both the handling of this event and sending it are	taken care  of
	     by	the ssh_client_channel behavior.

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

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

	   {env,  channel_id(),	 WantReply :: boolean(), Var ::string(), Value
	   :: string()}:
	     Environment variables can be passed to the	 shell/command	to  be
	     started  later.  This  event  is  sent  as	 a  result  of calling
	     ssh_connection:setenv/5.

	   {pty, channel_id(), WantReply :: boolean(), {Terminal ::  string(),
	   CharWidth ::	integer(), RowHeight ::	integer(), PixelWidth :: inte-
	   ger(), PixelHeight  ::  integer(),  TerminalModes  ::  [{Opcode  ::
	   atom() | integer(), Value ::	integer()}]}}:
	     A pseudo-terminal has been	requested for the session. Terminal is
	     the value of the TERM environment variable	value, that is,	vt100.
	     Zero  dimension parameters	must be	ignored. The character/row di-
	     mensions override the pixel dimensions (when non-zero). Pixel di-
	     mensions  refer to	the drawable area of the window. Opcode	in the
	     TerminalModes list	is the mnemonic	name, represented as a	lower-
	     case  Erlang atom,	defined	in RFC 4254, Section 8.	It can 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 a result of calling ssh_connection:ptty_alloc/4.

	   {shell, WantReply ::	boolean()}:
	     This message requests that	the user default shell is  started  at
	     the  other	 end.  This  event  is	sent  as  a  result of calling
	     ssh_connection:shell/2.

	   {window_change, channel_id(), CharWidth() ::	 integer(),  RowHeight
	   :: integer(), PixWidth :: integer(),	PixHeight :: integer()}:
	     When  the	window	(terminal) size	changes	on the client side, it
	     can send a	message	to the server side to inform it	of the new di-
	     mensions. No API function generates this event.

	   {exec, channel_id(),	WantReply :: boolean(),	Cmd :: string()}:
	     This  message  requests  that  the	server starts execution	of the
	     given command. This event is sent as a result of calling ssh_con-
	     nection:exec/4 .

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

	      Types:

		 ConnectionRef = connection_ref()
		 ChannelId = channel_id()
		 NumOfBytes = integer()

	      Adjusts  the SSH flow control window. This is to be done by both
	      the client- and server-side channel processes.

	  Note:
	      Channels implemented with	the   ssh_client_channel  behavior  do
	      not  normally need to call this function as flow control is han-
	      dled by the behavior. The	behavior adjusts the window every time
	      the  callback  handle_ssh_msg/2 returns after processing channel
	      data.

       close(ConnectionRef, ChannelId) -> ok

	      Types:

		 ConnectionRef = connection_ref()
		 ChannelId = channel_id()

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

	  Note:
	      This  function is	called by the ssh_client_channel behavior when
	      the channel is  terminated,  see	 ssh_client_channel(3).	 Thus,
	      channels	implemented  with  the	behavior  are not to call this
	      function explicitly.

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

	      Types:

		 ConnectionRef = connection_ref()
		 ChannelId = channel_id()
		 Command = string()
		 Timeout = timeout()

	      Is  to be	called by a client-channel process to request that the
	      server starts executing the given	command. The result is several
	      messages according to the	following pattern. The last message is
	      a	channel	close message, as the exec request is a	one-time  exe-
	      cution that closes the channel when it is	done.

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

		0 or 1 x {ssh_cm, connection_ref(), {eof, channel_id()}}:
		  Indicates that no more data is to be sent.

		0  or  1  x  {ssh_cm,  connection_ref(),  {exit_signal,	 chan-
		nel_id(), ExitSignal ::	string(), ErrorMsg ::  string(),  Lan-
		guageString :: string()}}:
		  Not  all  systems  send signals. For details on valid	string
		  values, see RFC 4254,	Section	6.10

		0  or  1  x  {ssh_cm,  connection_ref(),  {exit_status,	 chan-
		nel_id(), ExitStatus ::	integer()}}:
		  It  is  recommended  by  the SSH Connection Protocol to send
		  this message,	but that is not	always the case.

		1 x {ssh_cm, connection_ref(), {closed,	channel_id()}}:
		  Indicates that the ssh_client_channel	started	for the	execu-
		  tion of the command has now been shut	down.

       exit_status(ConnectionRef, ChannelId, Status) ->	ok

	      Types:

		 ConnectionRef = connection_ref()
		 ChannelId = channel_id()
		 Status	= integer()

	      Is  to  be  called  by a server-channel process to send 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 = connection_ref()
		 ChannelId = channel_id()
		 Options = proplists:proplist()

	      Sends  an	SSH Connection Protocol	pty_req, to allocate a pseudo-
	      terminal.	Is to be called	by an SSH client process.

	      Options:

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

		{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 can be	an empty list. Otherwise, see  possible	 POSIX
		  names	in Section 8 in	 RFC 4254.

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

	      Types:

		 ConnectionRef = connection_ref()
		 WantReply = boolean()
		 Status	= ssh_request_status()
		 ChannelId = channel_id()

	      Sends  status replies to requests	where the requester has	stated
	      that it wants a status report, that is,  WantReply  =  true.  If
	      WantReply	 is  false, calling this function becomes a "noop". Is
	      to be called while handling an SSH Connection  Protocol  message
	      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 = connection_ref()
		 ChannelId = channel_id()
		 Data =	binary()
		 Type =	ssh_data_type_code()
		 Timeout = timeout()

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

	      The function subsystem/4 and subsequent calls of send/3,4,5 must
	      be executed in the same process.

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

	      Types:

		 ConnectionRef = connection_ref()
		 ChannelId = channel_id()

	      Sends EOF	on channel ChannelId.

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

	      Types:

		 ConnectionRef = 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 functions  in
	      this module.

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

	      Types:

		 ConnectionRef = connection_ref()
		 ChannelId = channel_id()
		 Var = string()
		 Value = string()
		 Timeout = timeout()

	      Environment  variables  can  be  passed  before	starting   the
	      shell/command. Is	to be called by	a client channel processes.

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

	      Types:

		 ConnectionRef = connection_ref()
		 ChannelId = channel_id()

	      Is  to be	called by a client channel process to request that the
	      user default shell (typically defined  in	 /etc/passwd  in  Unix
	      systems) is executed at the server end.

	      Note:  the return	value is ok instead of success unlike in other
	      functions	in this	module.	This is	a fault	that was introduced so
	      long  ago	that any change	would break a large number of existing
	      software.

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

	      Types:

		 ConnectionRef = connection_ref()
		 ChannelId = channel_id()
		 Subsystem = string()
		 Timeout = timeout()

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

	      The function subsystem/4 and subsequent calls of send/3,4,5 must
	      be executed in the same process.

Ericsson AB			   ssh 4.7.4		     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+13.0-RELEASE+and+Ports>

home | help