1ssh(3)                     Erlang Module Definition                     ssh(3)
2
3
4

NAME

6       ssh - Main API of the ssh application
7

DESCRIPTION

9       This  is the interface module for the SSH application. The Secure Shell
10       (SSH) Protocol is a protocol for secure remote login and  other  secure
11       network  services  over  an insecure network. See ssh(6) for details of
12       supported RFCs, versions, algorithms and unicode handling.
13
14       With the SSH application it is possible to start clients  and to  start
15       daemons  (servers).
16
17       Clients  are  started with connect/2, connect/3 or connect/4. They open
18       an encrypted connection on top of TCP/IP. In that encrypted  connection
19       one  or more channels could be opened with ssh_connection:session_chan‐
20       nel/2,4.
21
22       Each channel is an isolated "pipe" between a client-side process and  a
23       server-side  process. Those process pairs could handle for example file
24       transfers (sftp) or remote command execution (shell, exec and/or  cli).
25       If  a custom shell is implemented, the user of the client could execute
26       the special commands remotely. Note that the user is not necessarily  a
27       human but probably a system interfacing the SSH app.
28
29       A  server-side  subssystem  (channel) server is requested by the client
30       with ssh_connection:subsystem/4.
31
32       A server (daemon) is started with daemon/1, daemon/2 or daemon/3.  Pos‐
33       sible channel handlers (subsystems) are declared with the subsystem op‐
34       tion when the daemon is started.
35
36       To just run a shell on a remote machine, there are functions that  bun‐
37       dles  the  needed three steps needed into one: shell/1,2,3. Similarily,
38       to just open an sftp (file transfer) connection to  a  remote  machine,
39       the simplest way is to use ssh_sftp:start_channel/1,2,3.
40
41       To   write   your   own  client  channel  handler,  use  the  behaviour
42       ssh_client_channel. For server channel handlers use  ssh_server_channel
43       behaviour (replaces ssh_daemon_channel).
44
45       Both clients and daemons accepts options that controls the exact behav‐
46       iour. Some options are common to both. The three sets are called Client
47       Options, Daemon Options and Common Options.
48
49       The  descriptions of the options uses the Erlang Type Language with ex‐
50       plaining text.
51
52   Note:
53       The User's Guide has examples and a Getting Started section.
54
55

KEYS AND FILES

57       A number of objects must be present for the SSH  application  to  work.
58       Those objects are per default stored in files. The default names, paths
59       and file formats are the same as for OpenSSH. Keys could  be  generated
60       with the ssh-keygen program from OpenSSH. See the User's Guide.
61
62       The paths could easily be changed by options: user_dir and system_dir.
63
64       A  completly different storage could be interfaced by writing call-back
65       modules    using    the    behaviours     ssh_client_key_api     and/or
66       ssh_server_key_api.  A  callback  module  is  installed with the option
67       key_cb to the client and/or the daemon.
68
69   Daemons
70       The keys are by default stored in files:
71
72         * Mandatory: one or more Host key(s) , both private and  public.  De‐
73           fault is to store them in the directory /etc/ssh in the files
74
75           * ssh_host_dsa_key and ssh_host_dsa_key.pub
76
77           * ssh_host_rsa_key and ssh_host_rsa_key.pub
78
79           * ssh_host_ecdsa_key and ssh_host_ecdsa_key.pub
80
81           The  host  keys  directory  could  be  changed with the option sys‐
82           tem_dir.
83
84         * Optional: one or more User's public key  in case of  publickey  au‐
85           thorization.  Default  is  to  store  them concatenated in the file
86           .ssh/authorized_keys in the user's home directory.
87
88           The user keys directory could be changed with the option user_dir.
89
90   Clients
91       The keys and some other data are by default stored in files in the  di‐
92       rectory .ssh in the user's home directory.
93
94       The directory could be changed with the option user_dir.
95
96         * Optional:  a  list  of Host public key(s)  for previously connected
97           hosts. This list is handled by the SSH application without any need
98           of  user  assistance.  The  default  is  to  store them in the file
99           known_hosts.
100
101           The host_accepting_client_options() are associated with  this  list
102           of keys.
103
104         * Optional:  one  or more User's private key(s)  in case of publickey
105           authorization. The default files are
106
107           * id_dsa and id_dsa.pub
108
109           * id_rsa and id_rsa.pub
110
111           * id_ecdsa and id_ecdsa.pub
112

DATA TYPES

114   Client Options
115       client_options() = [client_option()]
116
117       client_option() =
118           ssh_file:pubkey_passphrase_client_options() |
119           host_accepting_client_options() |
120           authentication_client_options() |
121           diffie_hellman_group_exchange_client_option() |
122           connect_timeout_client_option() |
123           recv_ext_info_client_option() |
124           opaque_client_options() |
125           gen_tcp:connect_option() |
126           common_option()
127
128              Options for clients. The  individual  options  are  further  ex‐
129              plained below or by following the hyperlinks.
130
131              Note  that  not  every gen_tcp:connect_option() is accepted. See
132              set_sock_opts/2 for a list of prohibited options.
133
134              Also note that setting a gen_tcp:connect_option()  could  change
135              the socket in a way that impacts the ssh client's behaviour neg‐
136              atively. You use it on your own risk.
137
138       host_accepting_client_options() =
139           {silently_accept_hosts, accept_hosts()} |
140           {user_interaction, boolean()} |
141           {save_accepted_host, boolean()} |
142           {quiet_mode, boolean()}
143
144       accept_hosts() =
145           boolean() |
146           accept_callback() |
147           {HashAlgoSpec :: fp_digest_alg(), accept_callback()}
148
149       fp_digest_alg() = md5 | crypto:sha1() | crypto:sha2()
150
151       accept_callback() =
152           fun((PeerName :: string(), fingerprint()) -> boolean()) |
153           fun((PeerName :: string(),
154                Port :: inet:port_number(),
155                fingerprint()) ->
156                   boolean())
157
158       fingerprint() = string() | [string()]
159
160                silently_accept_hosts:
161                  This option guides the connect function on how to  act  when
162                  the connected server presents a Host Key that the client has
163                  not seen before. The default is to ask the user with a ques‐
164                  tion  on  stdio  of whether to accept or reject the new Host
165                  Key. See the option user_dir for specifying the path to  the
166                  file  known_hosts  where  previously  accepted Host Keys are
167                  recorded. See also the option key_cb for the general way  to
168                  handle keys.
169
170                  The  option  can  be  given in three different forms as seen
171                  above:
172
173                  * The value is a boolean(). The value  true  will  make  the
174                    client accept any unknown Host Key without any user inter‐
175                    action. The value false preserves the default behaviour of
176                    asking the user on stdio.
177
178                  * An accept_callback() will be called and the boolean return
179                    value true will make the client accept the Host Key. A re‐
180                    turn  value  of  false  will make the client to reject the
181                    Host Key and as a result the connection  will  be  closed.
182                    The arguments to the fun are:
183
184                    * PeerName  - a string with the name or address of the re‐
185                      mote host.
186
187                    * FingerPrint - the fingerprint of the Host  Key  as  pub‐
188                      lic_key:ssh_hostkey_fingerprint/1 calculates it.
189
190                  * A  tuple {HashAlgoSpec, accept_callback}. The HashAlgoSpec
191                    specifies which hash algorithm shall be used to  calculate
192                    the fingerprint used in the call of the accept_callback().
193                    The HashALgoSpec is either an atom or a list of  atoms  as
194                    the   first   argument  in  public_key:ssh_hostkey_finger‐
195                    print/2. If it is a list of hash algorithm names, the Fin‐
196                    gerPrint  argument in the accept_callback() will be a list
197                    of fingerprints in the same  order  as  the  corresponding
198                    name in the HashAlgoSpec list.
199
200                user_interaction:
201                  If  false,  disables  the client to connect to the server if
202                  any user interaction is needed, such as accepting the server
203                  to  be  added  to the known_hosts file, or supplying a pass‐
204                  word.
205
206                  Even if user interaction is allowed it can be suppressed  by
207                  other  options,  such as silently_accept_hosts and password.
208                  However, those options are not always desirable to use  from
209                  a security point of view.
210
211                  Defaults to true.
212
213                save_accepted_host:
214                  If  true, the client saves an accepted host key to avoid the
215                  accept question the next time the same host is connected. If
216                  the  option  key_cb  is not present, the key is saved in the
217                  file "known_hosts". See option user_dir for the location  of
218                  that file.
219
220                  If false, the key is not saved and the key will still be un‐
221                  known at the next access of the same host.
222
223                  Defaults to true
224
225                quiet_mode:
226                  If true, the client does not print  anything  on  authoriza‐
227                  tion.
228
229                  Defaults to false
230
231       authentication_client_options() =
232           {user, string()} | {password, string()}
233
234                user:
235                  Provides  the  username.  If  this  option is not given, ssh
236                  reads from the environment (LOGNAME or USER on  UNIX,  USER‐
237                  NAME on Windows).
238
239                password:
240                  Provides a password for password authentication. If this op‐
241                  tion is not given, the user is asked for a password, if  the
242                  password authentication method is attempted.
243
244       diffie_hellman_group_exchange_client_option() =
245           {dh_gex_limits,
246            {Min :: integer() >= 1,
247             I :: integer() >= 1,
248             Max :: integer() >= 1}}
249
250              Sets  the  three  diffie-hellman-group-exchange  parameters that
251              guides the connected server in choosing a group.  See  RFC  4419
252              for the details. The default value is {1024, 6144, 8192}.
253
254       connect_timeout_client_option() = {connect_timeout, timeout()}
255
256              Sets  a timeout on the transport layer connect time. For gen_tcp
257              the time is in milli-seconds and the default value is infinity.
258
259              See the parameter Timeout in connect/4 for a timeout of the  ne‐
260              gotiation phase.
261
262       recv_ext_info_client_option() = {recv_ext_info, boolean()}
263
264              Make  the  client tell the server that the client accepts exten‐
265              sion negotiation, that is, include  ext-info-c  in  the  kexinit
266              message  sent. See RFC 8308 for details and ssh(6) for a list of
267              currently implemented extensions.
268
269              Default value is true which is compatible with other implementa‐
270              tions not supporting ext-info.
271
272   Daemon Options (Server Options)
273       daemon_options() = [daemon_option()]
274
275       daemon_option() =
276           subsystem_daemon_option() |
277           shell_daemon_option() |
278           exec_daemon_option() |
279           ssh_cli_daemon_option() |
280           tcpip_tunnel_out_daemon_option() |
281           tcpip_tunnel_in_daemon_option() |
282           authentication_daemon_options() |
283           diffie_hellman_group_exchange_daemon_option() |
284           negotiation_timeout_daemon_option() |
285           hello_timeout_daemon_option() |
286           hardening_daemon_options() |
287           callbacks_daemon_options() |
288           send_ext_info_daemon_option() |
289           opaque_daemon_options() |
290           gen_tcp:listen_option() |
291           common_option()
292
293              Options  for  daemons.  The  individual  options are further ex‐
294              plained below or by following the hyperlinks.
295
296              Note that not every  gen_tcp:listen_option()  is  accepted.  See
297              set_sock_opts/2 for a list of prohibited options.
298
299              Also  note  that  setting a gen_tcp:listen_option() could change
300              the socket in a way that impacts the ssh deamon's behaviour neg‐
301              atively. You use it on your own risk.
302
303       subsystem_daemon_option() = {subsystems, subsystem_specs()}
304
305       subsystem_specs() = [subsystem_spec()]
306
307       subsystem_spec() = {Name :: string(), mod_args()}
308
309              Defines a subsystem in the daemon.
310
311              The  subsystem_name  is the name that a client requests to start
312              with for example ssh_connection:subsystem/4.
313
314              The  channel_callback  is  the  module   that   implements   the
315              ssh_server_channel  (replaces  ssh_daemon_channel)  behaviour in
316              the daemon. See the section Creating a Subsystem in  the  User's
317              Guide for more information and an example.
318
319              If   the   subsystems  option  is  not  present,  the  value  of
320              ssh_sftpd:subsystem_spec([]) is used. This enables the sftp sub‐
321              system  by  default.  The option can be set to the empty list if
322              you do not want the daemon to run any subsystems.
323
324       shell_daemon_option() = {shell, shell_spec()}
325
326       shell_spec() = mod_fun_args() | shell_fun() | disabled
327
328       shell_fun() = 'shell_fun/1'() | 'shell_fun/2'()
329
330       'shell_fun/1'() = fun((User :: string()) -> pid())
331
332       'shell_fun/2'() =
333           fun((User :: string(), PeerAddr :: inet:ip_address()) -> pid())
334
335              Defines the read-eval-print loop used in a daemon when  a  shell
336              is  requested  by  the  client. The default is to use the Erlang
337              shell: {shell, start, []}
338
339              See the option exec-option for a description of how  the  daemon
340              executes  shell-requests  and  exec-requests  depending  on  the
341              shell- and exec-options.
342
343       exec_daemon_option() = {exec, exec_spec()}
344
345       exec_spec() =
346           {direct, exec_fun()} | disabled | deprecated_exec_opt()
347
348       exec_fun() = 'exec_fun/1'() | 'exec_fun/2'() | 'exec_fun/3'()
349
350       'exec_fun/1'() = fun((Cmd :: string()) -> exec_result())
351
352       'exec_fun/2'() =
353           fun((Cmd :: string(), User :: string()) -> exec_result())
354
355       'exec_fun/3'() =
356           fun((Cmd :: string(),
357                User :: string(),
358                ClientAddr :: ip_port()) ->
359                   exec_result())
360
361       exec_result() =
362           {ok, Result :: term()} | {error, Reason :: term()}
363
364              This option changes how the daemon executes  exec-requests  from
365              clients.  The  term in the return value is formatted to a string
366              if it is a non-string type. No trailing newline is added in  the
367              ok-case.
368
369              See the User's Guide section on One-Time Execution for examples.
370
371              Error  texts  are  returned  on  channel-type 1 which usually is
372              piped to stderr on e.g Linux systems. Texts  from  a  successful
373              execution  are  returned  on  channel-type 0 and will in similar
374              manner be piped to stdout. The exit-status code is set to 0  for
375              success  and  255 for errors. The exact results presented on the
376              client side depends on the client  and  the  client's  operating
377              system.
378
379              In case of the {direct, exec_fun()} variant or no exec-option at
380              all, all reads from standard_input will  be  from  the  received
381              data-events  of type 0. Those are sent by the client. Similarily
382              all writes to standard_output will be sent as data-events to the
383              client.  An  OS  shell client like the command 'ssh' will usally
384              use stdin and stdout for the user interface.
385
386              The option cooperates with the daemon-option shell in  the  fol‐
387              lowing way:
388
389                1.   If  neither  the  exec-option  nor  the  shell-option  is
390                present::
391                  The default Erlang evaluator is used both for exec and shell
392                  requests. The result is returned to the client.
393
394                2.  If the exec_spec's value is disabled (the shell-option may
395                or may not be present)::
396                  No exec-requests are executed but shell-requests are not af‐
397                  fected, they follow the shell_spec's value.
398
399                3.  If  the exec-option is present and the exec_spec value =/=
400                disabled (the shell-option may or may not be present)::
401                  The exec_spec fun() is called with the same number of param‐
402                  eters as the arity of the fun, and the result is returned to
403                  the client. Shell-requests are not affected, they follow the
404                  shell_spec's value.
405
406                4.  If  the  exec-option  is  absent,  and the shell-option is
407                present with the default  Erlang  shell  as  the  shell_spec's
408                value::
409                  The default Erlang evaluator is used both for exec and shell
410                  requests. The result is returned to the client.
411
412                5. If the exec-option  is  absent,  and  the  shell-option  is
413                present  with a value that is neither the default Erlang shell
414                nor the value disabled::
415                  The exec-request is not evaluated and an  error  message  is
416                  returned  to the client. Shell-requests are executed accord‐
417                  ing to the value of the shell_spec.
418
419                6. If the exec-option is absent, and the shell_spec's value is
420                disabled::
421                  Exec  requests are executed by the default shell, but shell-
422                  requests are not executed.
423
424              If a custom CLI is installed (see the option ssh_cli) the  rules
425              above are replaced by thoose implied by the custom CLI.
426
427          Note:
428              The  exec-option  has existed for a long time but has not previ‐
429              ously been documented. The old definition and behaviour are  re‐
430              tained  but obey the rules 1-6 above if conflicting. The old and
431              undocumented style should not be used in new programs.
432
433
434       deprecated_exec_opt() = function() | mod_fun_args()
435
436              Old-style exec specification that are  kept  for  compatibility,
437              but should not be used in new programs
438
439       ssh_cli_daemon_option() = {ssh_cli, mod_args() | no_cli}
440
441              Provides your own CLI implementation in a daemon.
442
443              It is a channel callback module that implements a shell and com‐
444              mand execution. The shell's read-eval-print loop can be  custom‐
445              ized,  using  the option shell. This means less work than imple‐
446              menting an own CLI channel. If ssh_cli is set to no_cli, the CLI
447              channels  like  shell  and  exec are disabled and only subsystem
448              channels are allowed.
449
450       authentication_daemon_options() =
451           ssh_file:system_dir_daemon_option() |
452           {auth_method_kb_interactive_data, prompt_texts()} |
453           {user_passwords, [{UserName :: string(), Pwd :: string()}]} |
454           {pk_check_user, boolean()} |
455           {password, string()} |
456           {pwdfun, pwdfun_2() | pwdfun_4()}
457
458       prompt_texts() =
459           kb_int_tuple() | kb_int_fun_3() | kb_int_fun_4()
460
461       kb_int_tuple() =
462           {Name :: string(),
463            Instruction :: string(),
464            Prompt :: string(),
465            Echo :: boolean()}
466
467       kb_int_fun_3() =
468           fun((Peer :: ip_port(), User :: string(), Service :: string()) ->
469                   kb_int_tuple())
470
471       kb_int_fun_4() =
472           fun((Peer :: ip_port(),
473                User :: string(),
474                Service :: string(),
475                State :: any()) ->
476                   kb_int_tuple())
477
478       pwdfun_2() =
479           fun((User :: string(), Password :: string() | pubkey) ->
480                   boolean())
481
482       pwdfun_4() =
483           fun((User :: string(),
484                Password :: string() | pubkey,
485                PeerAddress :: ip_port(),
486                State :: any()) ->
487                   boolean() |
488                   disconnect |
489                   {boolean(), NewState :: any()})
490
491                auth_method_kb_interactive_data:
492                  Sets the text strings that the daemon sends  to  the  client
493                  for presentation to the user when using keyboard-interactive
494                  authentication.
495
496                  If the fun/3 or fun/4 is used, it is called when the  actual
497                  authentication  occurs and may therefore return dynamic data
498                  like time, remote ip etc.
499
500                  The parameter Echo guides the client about need to hide  the
501                  password.
502
503                  The   default  value  is:  {auth_method_kb_interactive_data,
504                  {"SSH server", "Enter password for  \""++User++"\"",  "pass‐
505                  word: ", false}>
506
507                user_passwords:
508                  Provides  passwords  for  password authentication. The pass‐
509                  words are used when someone tries to connect to  the  server
510                  and  public  key  user-authentication fails. The option pro‐
511                  vides a list of valid usernames and the corresponding  pass‐
512                  words.
513
514                pk_check_user:
515                  Enables  checking  of  the  client's user name in the server
516                  when doing public key authentication. It is disabled by  de‐
517                  fault.
518
519                  The  term  "user"  is used differently in OpenSSH and SSH in
520                  Erlang/OTP: see more in the User's Guide.
521
522                  If the option is enabled, and no pwdfun is present, the user
523                  name  must  present  in  the user_passwords for the check to
524                  succeed but the value of the password is not checked.
525
526                  In case of a pwdfun checking the user, the  atom  pubkey  is
527                  put in the password argument.
528
529                password:
530                  Provides a global password that authenticates any user.
531
532            Warning:
533                Intended to facilitate testing.
534
535                From  a security perspective this option makes the server very
536                vulnerable.
537
538
539                pwdfun with pwdfun_4():
540                  Provides a function for password validation. This could used
541                  for calling an external system or handeling passwords stored
542                  as hash values.
543
544                  This fun can also be used to make delays  in  authentication
545                  tries for example by calling timer:sleep/1.
546
547                  To  facilitate  for  instance  counting of failed tries, the
548                  State variable could be used. This state is  per  connection
549                  only.  The first time the pwdfun is called for a connection,
550                  the State variable has the value undefined.
551
552                  The fun should return:
553
554                  * true if the user and password is valid
555
556                  * false if the user or password is invalid
557
558                  * disconnect if a SSH_MSG_DISCONNECT message should be  sent
559                    immediately.  It will be followed by a close of the under‐
560                    lying tcp connection.
561
562                  * {true, NewState:any()} if the user and password is valid
563
564                  * {false, NewState:any()} if the user or password is invalid
565
566                  A third usage is to block login attempts from a missbehaving
567                  peer.  The  State  described above can be used for this. The
568                  return value disconnect is useful for this.
569
570                  In case of the pk_check_user is set, the atom pubkey is  put
571                  in the password argument when validating a public key login.
572                  The pwdfun is then responsible to check that the  user  name
573                  is valid.
574
575                pwdfun with pwdfun_2():
576                  Provides  a  function for password validation. This function
577                  is called with user and password as strings, and returns:
578
579                  * true if the user and password is valid
580
581                  * false if the user or password is invalid
582
583                  In case of the pk_check_user is set, the atom pubkey is  put
584                  in the password argument when validating a public key login.
585                  The pwdfun is then responsible to check that the  user  name
586                  is valid.
587
588                  This variant is kept for compatibility.
589
590       diffie_hellman_group_exchange_daemon_option() =
591           {dh_gex_groups,
592            [explicit_group()] |
593            explicit_group_file() |
594            ssh_moduli_file()} |
595           {dh_gex_limits, {Min :: integer() >= 1, Max :: integer() >= 1}}
596
597       explicit_group() =
598           {Size :: integer() >= 1,
599            G :: integer() >= 1,
600            P :: integer() >= 1}
601
602       explicit_group_file() = {file, string()}
603
604       ssh_moduli_file() = {ssh_moduli_file, string()}
605
606                dh_gex_groups:
607                  Defines  the groups the server may choose among when diffie-
608                  hellman-group-exchange is negotiated. See RFC 4419  for  de‐
609                  tails. The three variants of this option are:
610
611                  {Size=integer(),G=integer(),P=integer()}:
612                    The groups are given explicitly in this list. There may be
613                    several elements with the same Size. In such a  case,  the
614                    server will choose one randomly in the negotiated Size.
615
616                  {file,filename()}:
617                    The  file  must  have one or more three-tuples {Size=inte‐
618                    ger(),G=integer(),P=integer()} terminated by  a  dot.  The
619                    file is read when the daemon starts.
620
621                  {ssh_moduli_file,filename()}:
622                    The  file  must  be  in ssh-keygen moduli file format. The
623                    file is read when the daemon starts.
624
625                  The default list is fetched from the public_key application.
626
627                dh_gex_limits:
628                  Limits what a client can ask for in diffie-hellman-group-ex‐
629                  change.  The  limits  will be {MaxUsed = min(MaxClient,Max),
630                  MinUsed = max(MinClient,Min)} where MaxClient and  MinClient
631                  are the values proposed by a connecting client.
632
633                  The default value is {0,infinity}.
634
635                  If  MaxUsed < MinUsed in a key exchange, it will fail with a
636                  disconnect.
637
638                  See RFC 4419 for the function of the Max and Min values.
639
640       hello_timeout_daemon_option() = {hello_timeout, timeout()}
641
642              Maximum time in milliseconds for the first part of the ssh  ses‐
643              sion setup, the hello message exchange. Defaults to 30000 ms (30
644              seconds). If the client fails to send the first  message  within
645              this time, the connection is closed.
646
647       negotiation_timeout_daemon_option() =
648           {negotiation_timeout, timeout()}
649
650              Maximum time in milliseconds for the authentication negotiation.
651              Defaults to 120000 ms (2 minutes). If the client fails to log in
652              within this time, the connection is closed.
653
654       hardening_daemon_options() =
655           {max_sessions, integer() >= 1} |
656           {max_channels, integer() >= 1} |
657           {parallel_login, boolean()} |
658           {minimal_remote_max_packet_size, integer() >= 1}
659
660                max_sessions:
661                  The  maximum  number  of  simultaneous sessions that are ac‐
662                  cepted at any time for this daemon. This  includes  sessions
663                  that  are being authorized. Thus, if set to N, and N clients
664                  have connected but not started the login process, connection
665                  attempt  N+1  is aborted. If N connections are authenticated
666                  and still logged in, no more logins are accepted  until  one
667                  of the existing ones log out.
668
669                  The  counter is per listening port. Thus, if two daemons are
670                  started,  one  with  {max_sessions,N}  and  the  other  with
671                  {max_sessions,M},  in total N+M connections are accepted for
672                  the whole ssh application.
673
674                  Notice that if parallel_login is false, only one client at a
675                  time can be in the authentication phase.
676
677                  By default, this option is not set. This means that the num‐
678                  ber is not limited.
679
680                max_channels:
681                  The maximum number of channels with active remote  subsystem
682                  that are accepted for each connection to this daemon
683
684                  By default, this option is not set. This means that the num‐
685                  ber is not limited.
686
687                parallel_login:
688                  If set to false (the default value), only one login is  han‐
689                  dled at a time. If set to true, an unlimited number of login
690                  attempts are allowed simultaneously.
691
692                  If the max_sessions option is set to N and parallel_login is
693                  set  to  true,  the maximum number of simultaneous login at‐
694                  tempts at any time is limited to N-K, where K is the  number
695                  of authenticated connections present at this daemon.
696
697            Warning:
698                Do not enable parallel_logins without protecting the server by
699                other means, for example, by  the  max_sessions  option  or  a
700                firewall configuration. If set to true, there is no protection
701                against DOS attacks.
702
703
704                minimal_remote_max_packet_size:
705                  The least maximum packet size that the daemon will accept in
706                  channel  open requests from the client. The default value is
707                  0.
708
709       callbacks_daemon_options() =
710           {failfun,
711            fun((User :: string(),
712                 PeerAddress :: inet:ip_address(),
713                 Reason :: term()) ->
714                    term())} |
715           {connectfun,
716            fun((User :: string(),
717                 PeerAddress :: inet:ip_address(),
718                 Method :: string()) ->
719                    term())}
720
721                connectfun:
722                  Provides a fun to implement your own logging when a user au‐
723                  thenticates to the server.
724
725                failfun:
726                  Provides  a  fun  to  implement your own logging when a user
727                  fails to authenticate.
728
729       send_ext_info_daemon_option() = {send_ext_info, boolean()}
730
731              Make the server (daemon) tell the client that the server accepts
732              extension  negotiation,  that is, include ext-info-s in the kex‐
733              init message sent. See RFC 8308 for details  and  ssh(6)  for  a
734              list of currently implemented extensions.
735
736              Default value is true which is compatible with other implementa‐
737              tions not supporting ext-info.
738
739       tcpip_tunnel_in_daemon_option() = {tcpip_tunnel_in, boolean()}
740
741              Enables (true) or disables (false) the possibility to  tunnel  a
742              TCP/IP connection in to a server. Disabled per default.
743
744       tcpip_tunnel_out_daemon_option() =
745           {tcpip_tunnel_out, boolean()}
746
747              Enables  (true)  or disables (false) the possibility to tunnel a
748              TCP/IP connection out of a server. Disabled per default.
749
750   Options common to clients and daemons
751       common_options() = [common_option()]
752
753       common_option() =
754           ssh_file:user_dir_common_option() |
755           profile_common_option() |
756           max_idle_time_common_option() |
757           key_cb_common_option() |
758           disconnectfun_common_option() |
759           unexpectedfun_common_option() |
760           ssh_msg_debug_fun_common_option() |
761           rekey_limit_common_option() |
762           id_string_common_option() |
763           pref_public_key_algs_common_option() |
764           preferred_algorithms_common_option() |
765           modify_algorithms_common_option() |
766           auth_methods_common_option() |
767           inet_common_option() |
768           fd_common_option()
769
770              The options above can be used both in  clients  and  in  daemons
771              (servers). They are further explained below.
772
773       profile_common_option() = {profile, atom()}
774
775              Used  together  with  ip-address and port to uniquely identify a
776              ssh daemon. This can be useful  in  a  virtualized  environment,
777              where there can be more that one server that has the same ip-ad‐
778              dress and port. If this property is not explicitly  set,  it  is
779              assumed that the the ip-address and port uniquely identifies the
780              SSH daemon.
781
782       max_idle_time_common_option() = {idle_time, timeout()}
783
784              Sets a time-out on a connection when no channels are  open.  De‐
785              faults to infinity. The unit is milliseconds.
786
787              The timeout is not active until channels are started, so it does
788              not limit the time from the connection  creation  to  the  first
789              channel opening.
790
791       rekey_limit_common_option() =
792           {rekey_limit,
793            Bytes ::
794                limit_bytes() |
795                {Minutes :: limit_time(), Bytes :: limit_bytes()}}
796
797       limit_bytes() = integer() >= 0 | infinity
798
799       limit_time() = integer() >= 1 | infinity
800
801              Sets  the  limit  when rekeying is to be initiated. Both the max
802              time and max amount of data could be configured:
803
804                * {Minutes, Bytes} initiate rekeying when any  of  the  limits
805                  are reached.
806
807                * Bytes  initiate  rekeying  when  Bytes  number  of bytes are
808                  transferred, or at latest after one hour.
809
810              When a rekeying is done, both the timer and the byte counter are
811              restarted. Defaults to one hour and one GByte.
812
813              If  Minutes  is set to infinity, no rekeying will ever occur due
814              to that max time has passed. Setting Bytes to infinity will  in‐
815              hibit  rekeying  after  a certain amount of data has been trans‐
816              ferred. If the option value is set to {infinity,  infinity},  no
817              rekeying  will be initiated. Note that rekeying initiated by the
818              peer will still be performed.
819
820       key_cb_common_option() =
821           {key_cb,
822            Module :: atom() | {Module :: atom(), Opts :: [term()]}}
823
824              Module  implementing  the  behaviour  ssh_client_key_api  and/or
825              ssh_server_key_api.  Can  be  used  to customize the handling of
826              public keys. If callback options are  provided  along  with  the
827              module  name, they are made available to the callback module via
828              the options passed to it under the key 'key_cb_private'.
829
830              The Opts defaults to [] when only the Module is specified.
831
832              The default value of this option is {ssh_file, []}. See also the
833              manpage of ssh_file.
834
835              A call to the call-back function F will be
836
837                     Module:F(..., [{key_cb_private,Opts}|UserOptions])
838
839
840              where  ...  are  arguments  to F as in ssh_client_key_api and/or
841              ssh_server_key_api. The UserOptions are  the  options  given  to
842              ssh:connect, ssh:shell or ssh:daemon.
843
844       pref_public_key_algs_common_option() =
845           {pref_public_key_algs, [pubkey_alg()]}
846
847              List of user (client) public key algorithms to try to use.
848
849              The  default  value is the public_key entry in the list returned
850              by ssh:default_algorithms/0.
851
852              If there is no public key of a  specified  type  available,  the
853              corresponding  entry  is ignored. Note that the available set is
854              dependent on the underlying cryptolib and current user's  public
855              keys.
856
857              See  also  the  option  user_dir  for specifying the path to the
858              user's keys.
859
860       disconnectfun_common_option() =
861           {disconnectfun, fun((Reason :: term()) -> void | any())}
862
863              Provides a fun to implement your own logging or  other  handling
864              at disconnects.
865
866       unexpectedfun_common_option() =
867           {unexpectedfun,
868            fun((Message :: term(), {Host :: term(), Port :: term()}) ->
869                    report | skip)}
870
871              Provides  a  fun  to  implement your own logging or other action
872              when an unexpected message arrives. If the  fun  returns  report
873              the  usual  info report is issued but if skip is returned no re‐
874              port is generated.
875
876       ssh_msg_debug_fun_common_option() =
877           {ssh_msg_debug_fun,
878            fun((ssh:connection_ref(),
879                 AlwaysDisplay :: boolean(),
880                 Msg :: binary(),
881                 LanguageTag :: binary()) ->
882                    any())}
883
884              Provide a fun to implement your own logging of the  SSH  message
885              SSH_MSG_DEBUG.  The  last three parameters are from the message,
886              see RFC 4253, section 11.3. The connection_ref() is  the  refer‐
887              ence  to the connection on which the message arrived. The return
888              value from the fun is not checked.
889
890              The default behaviour is ignore the message. To get  a  printout
891              for  each  message  with  AlwaysDisplay  = true, use for example
892              {ssh_msg_debug_fun, fun(_,true,M,_)->  io:format("DEBUG:  ~p~n",
893              [M]) end}
894
895       id_string_common_option() =
896           {id_string,
897            string() |
898            random |
899            {random, Nmin :: integer() >= 1, Nmax :: integer() >= 1}}
900
901              The  string  the  daemon  will present to a connecting peer ini‐
902              tially. The default value is "Erlang/VSN" where VSN is  the  ssh
903              application version number.
904
905              The  value  random  will  cause a random string to be created at
906              each connection attempt. This is to make it a bit more difficult
907              for a malicious peer to find the ssh software brand and version.
908
909              The value {random, Nmin, Nmax} will make a random string with at
910              least Nmin characters and at most Nmax characters.
911
912       preferred_algorithms_common_option() =
913           {preferred_algorithms, algs_list()}
914
915       algs_list() = [alg_entry()]
916
917       alg_entry() =
918           {kex, [kex_alg()]} |
919           {public_key, [pubkey_alg()]} |
920           {cipher, double_algs(cipher_alg())} |
921           {mac, double_algs(mac_alg())} |
922           {compression, double_algs(compression_alg())}
923
924       kex_alg() =
925           'diffie-hellman-group-exchange-sha1' |
926           'diffie-hellman-group-exchange-sha256' |
927           'diffie-hellman-group1-sha1' | 'diffie-hellman-group14-sha1' |
928           'diffie-hellman-group14-sha256' |
929           'diffie-hellman-group16-sha512' |
930           'diffie-hellman-group18-sha512' | 'curve25519-sha256' |
931           'curve25519-sha256@libssh.org' | 'curve448-sha512' |
932           'ecdh-sha2-nistp256' | 'ecdh-sha2-nistp384' |
933           'ecdh-sha2-nistp521'
934
935       pubkey_alg() =
936           'ecdsa-sha2-nistp256' | 'ecdsa-sha2-nistp384' |
937           'ecdsa-sha2-nistp521' | 'ssh-ed25519' | 'ssh-ed448' |
938           'rsa-sha2-256' | 'rsa-sha2-512' | 'ssh-dss' | 'ssh-rsa'
939
940       cipher_alg() =
941           '3des-cbc' | 'AEAD_AES_128_GCM' | 'AEAD_AES_256_GCM' |
942           'aes128-cbc' | 'aes128-ctr' | 'aes128-gcm@openssh.com' |
943           'aes192-ctr' | 'aes192-cbc' | 'aes256-cbc' | 'aes256-ctr' |
944           'aes256-gcm@openssh.com' | 'chacha20-poly1305@openssh.com'
945
946       mac_alg() =
947           'AEAD_AES_128_GCM' | 'AEAD_AES_256_GCM' | 'hmac-sha1' |
948           'hmac-sha1-etm@openssh.com' | 'hmac-sha1-96' |
949           'hmac-sha2-256' | 'hmac-sha2-512' |
950           'hmac-sha2-256-etm@openssh.com' |
951           'hmac-sha2-512-etm@openssh.com'
952
953       compression_alg() = none | zlib | 'zlib@openssh.com'
954
955       double_algs(AlgType) =
956           [{client2server, [AlgType]} | {server2client, [AlgType]}] |
957           [AlgType]
958
959              List of algorithms to use in the algorithm negotiation. The  de‐
960              fault algs_list() can be obtained from default_algorithms/0.
961
962              If  an  alg_entry()  is  missing in the algs_list(), the default
963              value is used for that entry.
964
965              Here is an example of this option:
966
967                     {preferred_algorithms,
968                     [{public_key,['ssh-rsa','ssh-dss']},
969                     {cipher,[{client2server,['aes128-ctr']},
970                        {server2client,['aes128-cbc','3des-cbc']}]},
971                     {mac,['hmac-sha2-256','hmac-sha1']},
972                     {compression,[none,zlib]}
973                     ]
974                     }
975
976
977              The example specifies different algorithms in the two directions
978              (client2server  and server2client), for cipher but specifies the
979              same algorithms for mac and compression in both directions.  The
980              kex (key exchange) is implicit but public_key is set explicitly.
981
982              For background and more examples see the User's Guide.
983
984              If an algorithm name occurs more than once in a list, the behav‐
985              iour is undefined. The tags in the property lists are  also  as‐
986              sumed to occur at most one time.
987
988          Warning:
989              Changing  the  values  can make a connection less secure. Do not
990              change unless you know exactly what you are doing. If you do not
991              understand the values then you are not supposed to change them.
992
993
994       modify_algorithms_common_option() =
995           {modify_algorithms, modify_algs_list()}
996
997       modify_algs_list() =
998           [{append, algs_list()} |
999            {prepend, algs_list()} |
1000            {rm, algs_list()}]
1001
1002              Modifies the list of algorithms to use in the algorithm negotia‐
1003              tion. The  modifications  are  applied  after  the  option  pre‐
1004              ferred_algorithms (if existing) is applied.
1005
1006              The algoritm for modifications works like this:
1007
1008                * Input  is  the  modify_algs_list() and a set of algorithms A
1009                  obtained from the preferred_algorithms option  if  existing,
1010                  or else from the ssh:default_algorithms/0.
1011
1012                * The head of the modify_algs_list() modifies A giving the re‐
1013                  sult A'.
1014
1015                  The possible modifications are:
1016
1017                  * Append or prepend supported but not  enabled  algorithm(s)
1018                    to  the  list  of algorithms. If the wanted algorithms al‐
1019                    ready are in A they will first be  removed  and  then  ap‐
1020                    pended or prepended,
1021
1022                  * Remove (rm) one or more algorithms from A.
1023
1024                * Repeat   the   modification  step  with  the  tail  of  mod‐
1025                  ify_algs_list() and the resulting A'.
1026
1027              If an unsupported algorithm is  in  the  modify_algs_list(),  it
1028              will be silently ignored
1029
1030              If there are more than one modify_algorithms options, the result
1031              is undefined.
1032
1033              Here is an example of this option:
1034
1035                     {modify_algorithms,
1036                     [{prepend, [{kex, ['diffie-hellman-group1-sha1']}],
1037                     {rm,      [{compression, [none]}]}
1038                     ]
1039                     }
1040
1041
1042              The example specifies that:
1043
1044                * the old key exchange algorithm  'diffie-hellman-group1-sha1'
1045                  should be the main alternative. It will be the main alterna‐
1046                  tive since it is prepened to the list
1047
1048                * The compression algorithm none (= no compression) is removed
1049                  so compression is enforced
1050
1051              For background and more examples see the User's Guide.
1052
1053       inet_common_option() = {inet, inet | inet6}
1054
1055              IP version to use when the host address is specified as any.
1056
1057       auth_methods_common_option() = {auth_methods, string()}
1058
1059              Comma-separated  string  that  determines  which  authentication
1060              methods that the client shall support and in  which  order  they
1061              are tried. Defaults to "publickey,keyboard-interactive,password"
1062
1063              Note  that  the  client  is free to use any order and to exclude
1064              methods.
1065
1066       fd_common_option() = {fd, gen_tcp:socket()}
1067
1068              Allows an existing file-descriptor to be used (passed on to  the
1069              transport protocol).
1070
1071   Other data types
1072       host() = string() | inet:ip_address() | loopback
1073
1074       ip_port() = {inet:ip_address(), inet:port_number()}
1075
1076       mod_args() = {Module :: atom(), Args :: list()}
1077
1078       mod_fun_args() =
1079           {Module :: atom(), Function :: atom(), Args :: list()}
1080
1081       open_socket() = gen_tcp:socket()
1082
1083              The  socket  is  supposed to be result of a gen_tcp:connect or a
1084              gen_tcp:accept. The socket must be in  passive  mode  (that  is,
1085              opened with the option {active,false}).
1086
1087       daemon_ref()
1088
1089              Opaque data type representing a daemon.
1090
1091              Returned by the functions daemon/1,2,3.
1092
1093       connection_ref()
1094
1095              Opaque  data type representing a connection between a client and
1096              a server (daemon).
1097
1098              Returned by the functions connect/2,3,4 and ssh_sftp:start_chan‐
1099              nel/2,3.
1100
1101       channel_id()
1102
1103              Opaque data type representing a channel inside a connection.
1104
1105              Returned by the functions ssh_connection:session_channel/2,4.
1106
1107       connection_info_tuple() =
1108           {client_version, version()} |
1109           {server_version, version()} |
1110           {user, string()} |
1111           {peer, {inet:hostname(), ip_port()}} |
1112           {sockname, ip_port()} |
1113           {options, client_options()} |
1114           {algorithms, conn_info_algs()} |
1115           {channels, conn_info_channels()}
1116
1117       version() = {protocol_version(), software_version()}
1118
1119       protocol_version() =
1120           {Major :: integer() >= 1, Minor :: integer() >= 0}
1121
1122       software_version() = string()
1123
1124       conn_info_algs() =
1125           [{kex, kex_alg()} |
1126            {hkey, pubkey_alg()} |
1127            {encrypt, cipher_alg()} |
1128            {decrypt, cipher_alg()} |
1129            {send_mac, mac_alg()} |
1130            {recv_mac, mac_alg()} |
1131            {compress, compression_alg()} |
1132            {decompress, compression_alg()} |
1133            {send_ext_info, boolean()} |
1134            {recv_ext_info, boolean()}]
1135
1136       conn_info_channels() = [proplists:proplist()]
1137
1138              Return  values  from the connection_info/1 and connection_info/2
1139              functions.
1140
1141              In the option info tuple are only the options included that dif‐
1142              fers from the default values.
1143
1144       daemon_info_tuple() =
1145           {port, inet:port_number()} |
1146           {ip, inet:ip_address()} |
1147           {profile, atom()} |
1148           {options, daemon_options()}
1149
1150              Return  values  from  the  daemon_info/1 and daemon_info/2 func‐
1151              tions.
1152
1153              In the option info tuple are only the options included that dif‐
1154              fers from the default values.
1155
1156       opaque_client_options()
1157
1158       opaque_daemon_options()
1159
1160       opaque_common_options()
1161
1162              Opaque types that define experimental options that are not to be
1163              used in products.
1164

EXPORTS

1166       close(ConnectionRef) -> ok | {error, term()}
1167
1168              Types:
1169
1170                 ConnectionRef = connection_ref()
1171
1172              Closes an SSH connection.
1173
1174       connect(Host, Port, Options) -> Result
1175       connect(Host, Port, Options, NegotiationTimeout) -> Result
1176       connect(TcpSocket, Options) -> Result
1177       connect(TcpSocket, Options, NegotiationTimeout) -> Result
1178
1179              Types:
1180
1181                 Host = host()
1182                 Port = inet:port_number()
1183                 Options = client_options()
1184                 TcpSocket = open_socket()
1185                 NegotiationTimeout = timeout()
1186                 Result = {ok, connection_ref()} | {error, term()}
1187
1188              Connects to an SSH server at the Host on Port.
1189
1190              As an alternative, an already open TCP socket could be passed to
1191              the  function  in  TcpSocket. The SSH initiation and negotiation
1192              will be initiated on that one with the SSH that should be at the
1193              other end.
1194
1195              No  channel  is  started.  This  is done by calling  ssh_connec‐
1196              tion:session_channel/[2, 4].
1197
1198              The NegotiationTimeout is in milli-seconds. The default value is
1199              infinity.  For  connection timeout, use the option connect_time‐
1200              out.
1201
1202       connection_info(ConnectionRef) -> InfoTupleList
1203
1204       connection_info(ConnectionRef, Key :: ItemList | Item) ->
1205                          InfoTupleList | InfoTuple
1206
1207              Types:
1208
1209                 ConnectionRef = connection_ref()
1210                 ItemList = [Item]
1211                 Item =
1212                     client_version | server_version | user | peer |  sockname
1213                 |
1214                     options | algorithms | sockname
1215                 InfoTupleList = [InfoTuple]
1216                 InfoTuple = connection_info_tuple()
1217
1218              Returns  information  about a connection intended for e.g debug‐
1219              ging or logging.
1220
1221              When the Key is a single Item, the result is a single InfoTuple
1222
1223       set_sock_opts(ConnectionRef, SocketOptions) ->
1224                        ok | {error, inet:posix()}
1225
1226              Types:
1227
1228                 ConnectionRef = connection_ref()
1229                 SocketOptions = [gen_tcp:option()]
1230
1231              Sets tcp socket options on the tcp-socket below an  ssh  connec‐
1232              tion.
1233
1234              This  function calls the inet:setopts/2, read that documentation
1235              and for gen_tcp:option().
1236
1237              All gen_tcp socket options except
1238
1239                * active
1240
1241                * deliver
1242
1243                * mode and
1244
1245                * packet
1246
1247              are allowed. The excluded options are reserved by the SSH appli‐
1248              cation.
1249
1250          Warning:
1251              This  is  an extremly dangerous function. You use it on your own
1252              risk.
1253
1254              Some options are OS and OS version dependent. Do not use it  un‐
1255              less you know what effect your option values will have on an TCP
1256              stream.
1257
1258              Some values may destroy the functionality of the SSH protocol.
1259
1260
1261       get_sock_opts(ConnectionRef, SocketGetOptions) ->
1262                        ok | {error, inet:posix()}
1263
1264              Types:
1265
1266                 ConnectionRef = connection_ref()
1267                 SocketGetOptions = [gen_tcp:option_name()]
1268
1269              Get tcp socket option values of the tcp-socket below an ssh con‐
1270              nection.
1271
1272              This function calls the inet:getopts/2, read that documentation.
1273
1274       daemon(Port | TcpSocket) -> Result
1275       daemon(Port | TcpSocket, Options) -> Result
1276       daemon(HostAddress, Port, Options) -> Result
1277
1278              Types:
1279
1280                 Port = integer()
1281                 TcpSocket = open_socket()
1282                 Options = daemon_options()
1283                 HostAddress = host() | any
1284                 Result = {ok, daemon_ref()} | {error, atom()}
1285
1286              Starts a server listening for SSH connections on the given port.
1287              If the Port is 0, a random  free  port  is  selected.  See  dae‐
1288              mon_info/1 about how to find the selected port number.
1289
1290              As an alternative, an already open TCP socket could be passed to
1291              the function in TcpSocket. The SSH  initiation  and  negotiation
1292              will  be  initiated  on that one when an SSH starts at the other
1293              end of the TCP socket.
1294
1295              For a description of the options, see Daemon Options.
1296
1297              Please note that by historical reasons both the HostAddress  ar‐
1298              gument  and  the  gen_tcp  connect_option() {ip,Address} set the
1299              listening address. This is a  source  of  possible  inconsistent
1300              settings.
1301
1302              The rules for handling the two address passing options are:
1303
1304                * if HostAddress is an IP-address, that IP-address is the lis‐
1305                  tening address. An 'ip'-option will be discarded if present.
1306
1307                * if HostAddress is the atom loopback, the  listening  address
1308                  is  loopback  and an loopback address will be choosen by the
1309                  underlying layers.  An  'ip'-option  will  be  discarded  if
1310                  present.
1311
1312                * if  HostAddress  is  the  atom  any  and  no  'ip'-option is
1313                  present, the listening address is any and  the  socket  will
1314                  listen to all addresses
1315
1316                * if  HostAddress  is  any  and an 'ip'-option is present, the
1317                  listening address is set to the value of the 'ip'-option
1318
1319       daemon_info(DaemonRef) ->
1320                      {ok, InfoTupleList} | {error, bad_daemon_ref}
1321
1322       daemon_info(DaemonRef, Key :: ItemList | Item) ->
1323                      InfoTupleList | InfoTuple | {error, bad_daemon_ref}
1324
1325              Types:
1326
1327                 DaemonRef = daemon_ref()
1328                 ItemList = [Item]
1329                 Item = ip | port | profile | options
1330                 InfoTupleList = [InfoTuple]
1331                 InfoTuple = daemon_info_tuple()
1332
1333              Returns information about a daemon intended for e.g debugging or
1334              logging.
1335
1336              When the Key is a single Item, the result is a single InfoTuple
1337
1338              Note  that  daemon_info/1  and  daemon_info/2  returns different
1339              types due to compatibility reasons.
1340
1341       default_algorithms() -> algs_list()
1342
1343              Returns a key-value list, where the keys are the different types
1344              of algorithms and the values are the algorithms themselves.
1345
1346              See the User's Guide for an example.
1347
1348       shell(Host | TcpSocket) -> Result
1349       shell(Host | TcpSocket, Options) -> Result
1350       shell(Host, Port, Options) -> Result
1351
1352              Types:
1353
1354                 Host = host()
1355                 TcpSocket = open_socket()
1356                 Port = inet:port_number()
1357                 Options = client_options()
1358                 Result = ok | {error, Reason::term()}
1359
1360              Connects  to an SSH server at Host and Port (defaults to 22) and
1361              starts an interactive shell on that remote host.
1362
1363              As an alternative, an already open TCP socket could be passed to
1364              the  function  in  TcpSocket. The SSH initiation and negotiation
1365              will be initiated on that one and finaly a shell will be started
1366              on the host at the other end of the TCP socket.
1367
1368              For a description of the options, see Client Options.
1369
1370              The function waits for user input, and does not return until the
1371              remote shell is ended (that is, exit from the shell).
1372
1373       start() -> ok | {error, term()}
1374
1375       start(Type) -> ok | {error, term()}
1376
1377              Types:
1378
1379                 Type = permanent | transient | temporary
1380
1381              Utility function  that  starts  the  applications  crypto,  pub‐
1382              lic_key,  and  ssh. Default type is temporary. For more informa‐
1383              tion, see the application(3) manual page in Kernel.
1384
1385       stop() -> ok | {error, term()}
1386
1387              Stops the ssh application. For more information, see the  appli‐
1388              cation(3) manual page in Kernel.
1389
1390       stop_daemon(DaemonRef :: daemon_ref()) -> ok
1391
1392       stop_daemon(Address :: inet:ip_address(),
1393                   Port :: inet:port_number()) ->
1394                      ok
1395
1396       stop_daemon(Address :: any | inet:ip_address(),
1397                   Port :: inet:port_number(),
1398                   Profile :: atom()) ->
1399                      ok
1400
1401              Stops the listener and all connections started by the listener.
1402
1403       stop_listener(SysSup :: daemon_ref()) -> ok
1404
1405       stop_listener(Address :: inet:ip_address(),
1406                     Port :: inet:port_number()) ->
1407                        ok
1408
1409       stop_listener(Address :: any | inet:ip_address(),
1410                     Port :: inet:port_number(),
1411                     Profile :: term()) ->
1412                        ok
1413
1414              Stops  the  listener, but leaves existing connections started by
1415              the listener operational.
1416
1417       tcpip_tunnel_from_server(ConnectionRef, ListenHost, ListenPort,
1418                                ConnectToHost, ConnectToPort) ->
1419                                   {ok, TrueListenPort} | {error, term()}
1420
1421       tcpip_tunnel_from_server(ConnectionRef, ListenHost, ListenPort,
1422                                ConnectToHost, ConnectToPort, Timeout) ->
1423                                   {ok, TrueListenPort} | {error, term()}
1424
1425              Types:
1426
1427                 ConnectionRef = connection_ref()
1428                 ListenHost = host()
1429                 ListenPort = inet:port_number()
1430                 ConnectToHost = host()
1431                 ConnectToPort = inet:port_number()
1432                 Timeout = timeout()
1433                 TrueListenPort = inet:port_number()
1434
1435              Asks the remote server of ConnectionRef  to  listen  to  Listen‐
1436              Host:ListenPort. When someone connects that address, the connec‐
1437              tion is forwarded in an encrypted channel from the server to the
1438              client.  The  client (that is, at the node that calls this func‐
1439              tion) then connects to ConnectToHost:ConnectToPort.
1440
1441              The returned TrueListenPort is the port that is listened to.  It
1442              is  the  same as ListenPort, except when ListenPort = 0. In that
1443              case a free port is selected by the underlying OS.
1444
1445              Note that in case of an Erlang/OTP SSH server (daemon) as  peer,
1446              that  server  must  have been started with the option tcpip_tun‐
1447              nel_out to allow the connection.
1448
1449       tcpip_tunnel_to_server(ConnectionRef, ListenHost, ListenPort,
1450                              ConnectToHost, ConnectToPort) ->
1451                                 {ok, TrueListenPort} | {error, term()}
1452
1453       tcpip_tunnel_to_server(ConnectionRef, ListenHost, ListenPort,
1454                              ConnectToHost, ConnectToPort, Timeout) ->
1455                                 {ok, TrueListenPort} | {error, term()}
1456
1457              Types:
1458
1459                 ConnectionRef = connection_ref()
1460                 ListenHost = host()
1461                 ListenPort = inet:port_number()
1462                 ConnectToHost = host()
1463                 ConnectToPort = inet:port_number()
1464                 Timeout = timeout()
1465                 TrueListenPort = inet:port_number()
1466
1467              Tells the local client to listen to ListenHost:ListenPort.  When
1468              someone connects to that address, the connection is forwarded in
1469              an encrypted channel to the peer server of  ConnectionRef.  That
1470              server then connects to ConnectToHost:ConnectToPort.
1471
1472              The  returned TrueListenPort is the port that is listened to. It
1473              is the same as ListenPort, except when ListenPort = 0.  In  that
1474              case a free port is selected by the underlying OS.
1475
1476              Note  that in case of an Erlang/OTP SSH server (daemon) as peer,
1477              that server must have been started with  the  option  tcpip_tun‐
1478              nel_in to allow the connection.
1479
1480
1481
1482Ericsson AB                      ssh 4.11.1.2                           ssh(3)
Impressum