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

EXPORTS

1212       close(ConnectionRef) -> ok | {error, term()}
1213
1214              Types:
1215
1216                 ConnectionRef = connection_ref()
1217
1218              Closes an SSH connection.
1219
1220       connect(Host, Port, Options) -> Result
1221       connect(Host, Port, Options, NegotiationTimeout) -> Result
1222       connect(TcpSocket, Options) -> Result
1223       connect(TcpSocket, Options, NegotiationTimeout) -> Result
1224
1225              Types:
1226
1227                 Host = host()
1228                 Port = inet:port_number()
1229                 Options = client_options()
1230                 TcpSocket = open_socket()
1231                 NegotiationTimeout = timeout()
1232                 Result = {ok, connection_ref()} | {error, term()}
1233
1234              Connects to an SSH server at the Host on Port.
1235
1236              As an alternative, an already open TCP socket could be passed to
1237              the  function  in  TcpSocket. The SSH initiation and negotiation
1238              will be initiated on that one with the SSH that should be at the
1239              other end.
1240
1241              No  channel  is  started.  This  is done by calling  ssh_connec‐
1242              tion:session_channel/[2, 4].
1243
1244              The NegotiationTimeout is in milli-seconds. The default value is
1245              infinity or the value of the connect_timeout option, if present.
1246              For connection timeout, use the option connect_timeout.
1247
1248       connection_info(ConnectionRef) -> InfoTupleList
1249
1250       connection_info(ConnectionRef, Key :: ItemList | Item) ->
1251                          InfoTupleList | InfoTuple
1252
1253              Types:
1254
1255                 ConnectionRef = connection_ref()
1256                 ItemList = [Item]
1257                 Item =
1258                     client_version | server_version | user | peer |  sockname
1259                 |
1260                     options | algorithms | sockname
1261                 InfoTupleList = [InfoTuple]
1262                 InfoTuple = connection_info_tuple()
1263
1264              Returns  information  about a connection intended for e.g debug‐
1265              ging or logging.
1266
1267              When the Key is a single Item, the result is a single InfoTuple
1268
1269       set_sock_opts(ConnectionRef, SocketOptions) ->
1270                        ok | {error, inet:posix()}
1271
1272              Types:
1273
1274                 ConnectionRef = connection_ref()
1275                 SocketOptions = [gen_tcp:option()]
1276
1277              Sets tcp socket options on the tcp-socket below an  ssh  connec‐
1278              tion.
1279
1280              This  function calls the inet:setopts/2, read that documentation
1281              and for gen_tcp:option().
1282
1283              All gen_tcp socket options except
1284
1285                * active
1286
1287                * deliver
1288
1289                * mode and
1290
1291                * packet
1292
1293              are allowed. The excluded options are reserved by the SSH appli‐
1294              cation.
1295
1296          Warning:
1297              This  is an extremely dangerous function. You use it on your own
1298              risk.
1299
1300              Some options are OS and OS version dependent. Do not use it  un‐
1301              less you know what effect your option values will have on an TCP
1302              stream.
1303
1304              Some values may destroy the functionality of the SSH protocol.
1305
1306
1307       get_sock_opts(ConnectionRef, SocketGetOptions) ->
1308                        ok | {error, inet:posix()}
1309
1310              Types:
1311
1312                 ConnectionRef = connection_ref()
1313                 SocketGetOptions = [gen_tcp:option_name()]
1314
1315              Get tcp socket option values of the tcp-socket below an ssh con‐
1316              nection.
1317
1318              This function calls the inet:getopts/2, read that documentation.
1319
1320       daemon(Port | TcpSocket) -> Result
1321       daemon(Port | TcpSocket, Options) -> Result
1322       daemon(HostAddress, Port, Options) -> Result
1323
1324              Types:
1325
1326                 Port = integer()
1327                 TcpSocket = open_socket()
1328                 Options = daemon_options()
1329                 HostAddress = host() | any
1330                 Result = {ok, daemon_ref()} | {error, atom()}
1331
1332              Starts a server listening for SSH connections on the given port.
1333              If the Port is 0, a random  free  port  is  selected.  See  dae‐
1334              mon_info/1 about how to find the selected port number.
1335
1336              As an alternative, an already open TCP socket could be passed to
1337              the function in TcpSocket. The SSH  initiation  and  negotiation
1338              will  be  initiated  on that one when an SSH starts at the other
1339              end of the TCP socket.
1340
1341              For a description of the options, see Daemon Options.
1342
1343              Please note that by historical reasons both the HostAddress  ar‐
1344              gument  and  the  gen_tcp  connect_option() {ip,Address} set the
1345              listening address. This is a  source  of  possible  inconsistent
1346              settings.
1347
1348              The rules for handling the two address passing options are:
1349
1350                * if HostAddress is an IP-address, that IP-address is the lis‐
1351                  tening address. An 'ip'-option will be discarded if present.
1352
1353                * if HostAddress is the atom loopback, the  listening  address
1354                  is  loopback  and  an loopback address will be chosen by the
1355                  underlying layers.  An  'ip'-option  will  be  discarded  if
1356                  present.
1357
1358                * if  HostAddress  is  the  atom  any  and  no  'ip'-option is
1359                  present, the listening address is any and  the  socket  will
1360                  listen to all addresses
1361
1362                * if  HostAddress  is  any  and an 'ip'-option is present, the
1363                  listening address is set to the value of the 'ip'-option
1364
1365       daemon_replace_options(DaemonRef, NewUserOptions) ->
1366                                 {ok, daemon_ref()} | {error, term()}
1367
1368              Types:
1369
1370                 DaemonRef = daemon_ref()
1371                 NewUserOptions = daemon_options()
1372
1373              Replaces the options in a running daemon  with  the  options  in
1374              NewUserOptions. Only connections established after this call are
1375              affected, already established connections are not.
1376
1377          Note:
1378              In the final phase of this function, the  listening  process  is
1379              restarted.  Therfore  a connection attempt to the daemon in this
1380              final phase could fail.
1381
1382
1383              The handling of Erlang configurations is described in the User's
1384              Guide;  see  chapters Configuration in SSH and Configuring algo‐
1385              rithms in SSH.
1386
1387       daemon_info(DaemonRef) ->
1388                      {ok, InfoTupleList} | {error, bad_daemon_ref}
1389
1390       daemon_info(DaemonRef, Key :: ItemList | Item) ->
1391                      InfoTupleList | InfoTuple | {error, bad_daemon_ref}
1392
1393              Types:
1394
1395                 DaemonRef = daemon_ref()
1396                 ItemList = [Item]
1397                 Item = ip | port | profile | options
1398                 InfoTupleList = [InfoTuple]
1399                 InfoTuple = daemon_info_tuple()
1400
1401              Returns information about a daemon intended for e.g debugging or
1402              logging.
1403
1404              When the Key is a single Item, the result is a single InfoTuple
1405
1406              Note  that  daemon_info/1  and  daemon_info/2  returns different
1407              types due to compatibility reasons.
1408
1409       default_algorithms() -> algs_list()
1410
1411              Returns a key-value list, where the keys are the different types
1412              of algorithms and the values are the algorithms themselves.
1413
1414              See the User's Guide for an example.
1415
1416       shell(Host | TcpSocket) -> Result
1417       shell(Host | TcpSocket, Options) -> Result
1418       shell(Host, Port, Options) -> Result
1419
1420              Types:
1421
1422                 Host = host()
1423                 TcpSocket = open_socket()
1424                 Port = inet:port_number()
1425                 Options = client_options()
1426                 Result = ok | {error, Reason::term()}
1427
1428              Connects  to an SSH server at Host and Port (defaults to 22) and
1429              starts an interactive shell on that remote host.
1430
1431              As an alternative, an already open TCP socket could be passed to
1432              the  function  in  TcpSocket. The SSH initiation and negotiation
1433              will be initiated on that  one  and  finally  a  shell  will  be
1434              started on the host at the other end of the TCP socket.
1435
1436              For a description of the options, see Client Options.
1437
1438              The function waits for user input, and does not return until the
1439              remote shell is ended (that is, exit from the shell).
1440
1441       start() -> ok | {error, term()}
1442
1443       start(Type) -> ok | {error, term()}
1444
1445              Types:
1446
1447                 Type = permanent | transient | temporary
1448
1449              Utility function  that  starts  the  applications  crypto,  pub‐
1450              lic_key,  and  ssh. Default type is temporary. For more informa‐
1451              tion, see the application(3) manual page in Kernel.
1452
1453       stop() -> ok | {error, term()}
1454
1455              Stops the ssh application. For more information, see the  appli‐
1456              cation(3) manual page in Kernel.
1457
1458       stop_daemon(DaemonRef :: daemon_ref()) -> ok
1459
1460       stop_daemon(Address :: inet:ip_address(),
1461                   Port :: inet:port_number()) ->
1462                      ok
1463
1464       stop_daemon(Address :: any | inet:ip_address(),
1465                   Port :: inet:port_number(),
1466                   Profile :: atom()) ->
1467                      ok
1468
1469              Stops the listener and all connections started by the listener.
1470
1471       stop_listener(SysSup :: daemon_ref()) -> ok
1472
1473       stop_listener(Address :: inet:ip_address(),
1474                     Port :: inet:port_number()) ->
1475                        ok
1476
1477       stop_listener(Address :: any | inet:ip_address(),
1478                     Port :: inet:port_number(),
1479                     Profile :: term()) ->
1480                        ok
1481
1482              Stops  the  listener, but leaves existing connections started by
1483              the listener operational.
1484
1485       tcpip_tunnel_from_server(ConnectionRef, ListenHost, ListenPort,
1486                                ConnectToHost, ConnectToPort) ->
1487                                   {ok, TrueListenPort} | {error, term()}
1488
1489       tcpip_tunnel_from_server(ConnectionRef, ListenHost, ListenPort,
1490                                ConnectToHost, ConnectToPort, Timeout) ->
1491                                   {ok, TrueListenPort} | {error, term()}
1492
1493              Types:
1494
1495                 ConnectionRef = connection_ref()
1496                 ListenHost = host()
1497                 ListenPort = inet:port_number()
1498                 ConnectToHost = host()
1499                 ConnectToPort = inet:port_number()
1500                 Timeout = timeout()
1501                 TrueListenPort = inet:port_number()
1502
1503              Asks the remote server of ConnectionRef  to  listen  to  Listen‐
1504              Host:ListenPort. When someone connects that address, the connec‐
1505              tion is forwarded in an encrypted channel from the server to the
1506              client.  The  client (that is, at the node that calls this func‐
1507              tion) then connects to ConnectToHost:ConnectToPort.
1508
1509              The returned TrueListenPort is the port that is listened to.  It
1510              is  the  same as ListenPort, except when ListenPort = 0. In that
1511              case a free port is selected by the underlying OS.
1512
1513              Note that in case of an Erlang/OTP SSH server (daemon) as  peer,
1514              that  server  must  have been started with the option tcpip_tun‐
1515              nel_out to allow the connection.
1516
1517       tcpip_tunnel_to_server(ConnectionRef, ListenHost, ListenPort,
1518                              ConnectToHost, ConnectToPort) ->
1519                                 {ok, TrueListenPort} | {error, term()}
1520
1521       tcpip_tunnel_to_server(ConnectionRef, ListenHost, ListenPort,
1522                              ConnectToHost, ConnectToPort, Timeout) ->
1523                                 {ok, TrueListenPort} | {error, term()}
1524
1525              Types:
1526
1527                 ConnectionRef = connection_ref()
1528                 ListenHost = host()
1529                 ListenPort = inet:port_number()
1530                 ConnectToHost = host()
1531                 ConnectToPort = inet:port_number()
1532                 Timeout = timeout()
1533                 TrueListenPort = inet:port_number()
1534
1535              Tells the local client to listen to ListenHost:ListenPort.  When
1536              someone connects to that address, the connection is forwarded in
1537              an encrypted channel to the peer server of  ConnectionRef.  That
1538              server then connects to ConnectToHost:ConnectToPort.
1539
1540              The  returned TrueListenPort is the port that is listened to. It
1541              is the same as ListenPort, except when ListenPort = 0.  In  that
1542              case a free port is selected by the underlying OS.
1543
1544              Note  that in case of an Erlang/OTP SSH server (daemon) as peer,
1545              that server must have been started with  the  option  tcpip_tun‐
1546              nel_in to allow the connection.
1547
1548       hostkey_fingerprint(HostKey) -> string()
1549       hostkey_fingerprint(DigestType, HostKey) -> string()
1550       hostkey_fingerprint([DigestType], HostKey) -> [string()]
1551
1552              Types:
1553
1554                 HostKey = public_key:public_key()
1555                 DigestType = public_key:digest_type()
1556
1557              Calculates  a  ssh fingerprint from a public host key as openssh
1558              does.
1559
1560              The algorithm in hostkey_fingerprint/1 is md5 to  be  compatible
1561              with older ssh-keygen commands. The string from the second vari‐
1562              ant is prepended by the algorithm name in uppercase as in  newer
1563              ssh-keygen commands.
1564
1565              Examples:
1566
1567               2> ssh:hostkey_fingerprint(Key).
1568               "f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"
1569
1570               3> ssh:hostkey_fingerprint(md5,Key).
1571               "MD5:f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"
1572
1573               4> ssh:hostkey_fingerprint(sha,Key).
1574               "SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY"
1575
1576               5> ssh:hostkey_fingerprint(sha256,Key).
1577               "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"
1578
1579               6> ssh:hostkey_fingerprint([sha,sha256],Key).
1580               ["SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY",
1581                "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"]
1582
1583
1584
1585
1586Ericsson AB                        ssh 5.0.1                            ssh(3)
Impressum