1ssh(3) Erlang Module Definition ssh(3)
2
6 ssh - Main API of the ssh application
7
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 With the SSH application it is possible to start clients and to start
15 daemons (servers).
16 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 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 A server-side subssystem (channel) server is requested by the client
30 with ssh_connection:subsystem/4.
31 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 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 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 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 The descriptions of the options uses the Erlang Type Language with ex‐
50 plaining text.
51 Note:
53 The User's Guide has examples and a Getting Started section.
54
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 The paths could easily be changed by options: user_dir and system_dir.
63 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 Daemons
70 The keys are by default stored in files:
71 * 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 * ssh_host_dsa_key and ssh_host_dsa_key.pub
76 * ssh_host_rsa_key and ssh_host_rsa_key.pub
78 * ssh_host_ecdsa_key and ssh_host_ecdsa_key.pub
80 The host keys directory could be changed with the option sys‐
82 tem_dir.
83 * 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 The user keys directory could be changed with the option user_dir.
89 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 The directory could be changed with the option user_dir.
95 * 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 The host_accepting_client_options() are associated with this list
102 of keys.
103 * Optional: one or more User's private key(s) in case of publickey
105 authorization. The default files are
106 * id_dsa and id_dsa.pub
108 * id_rsa and id_rsa.pub
110 * id_ecdsa and id_ecdsa.pub
112
114 Client Options
115 client_options() = [client_option()]
116 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 Options for clients. The individual options are further ex‐
129 plained below or by following the hyperlinks.
130 Note that not every gen_tcp:connect_option() is accepted. See
132 set_sock_opts/2 for a list of prohibited options.
133 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 host_accepting_client_options() =
139 {silently_accept_hosts, accept_hosts()} |
140 {user_interaction, boolean()} |
141 {save_accepted_host, boolean()} |
142 {quiet_mode, boolean()}
143 accept_hosts() =
145 boolean() |
146 accept_callback() |
147 {HashAlgoSpec :: fp_digest_alg(), accept_callback()}
148 fp_digest_alg() = md5 | crypto:sha1() | crypto:sha2()
150 accept_callback() =
152 fun((PeerName :: string(), fingerprint()) -> boolean()) |
153 fun((PeerName :: string(),
154 Port :: inet:port_number(),
155 fingerprint()) ->
156 boolean())
157 fingerprint() = string() | [string()]
159 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 The option can be given in three different forms as seen
171 above:
172 * 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 * 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 * PeerName - a string with the name or address of the re‐
185 mote host.
186 * FingerPrint - the fingerprint of the Host Key as
188 hostkey_fingerprint/1 calculates it.
189 * 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 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 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 Defaults to true.
212 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 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 Defaults to true
224 quiet_mode:
226 If true, the client does not print anything on authoriza‐
227 tion.
228 Defaults to false
230 authentication_client_options() =
232 {user, string()} | {password, string()}
233 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 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 diffie_hellman_group_exchange_client_option() =
245 {dh_gex_limits,
246 {Min :: integer() >= 1,
247 I :: integer() >= 1,
248 Max :: integer() >= 1}}
249 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 connect_timeout_client_option() = {connect_timeout, timeout()}
255 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 See the parameter Timeout in connect/4 for a timeout of the ne‐
260 gotiation phase.
261 recv_ext_info_client_option() = {recv_ext_info, boolean()}
263 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 Default value is true which is compatible with other implementa‐
270 tions not supporting ext-info.
271 Daemon Options (Server Options)
273 daemon_options() = [daemon_option()]
274 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 Options for daemons. The individual options are further ex‐
295 plained below or by following the hyperlinks.
296 Note that not every gen_tcp:listen_option() is accepted. See
298 set_sock_opts/2 for a list of prohibited options.
299 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 subsystem_daemon_option() = {subsystems, subsystem_specs()}
305 subsystem_specs() = [subsystem_spec()]
307 subsystem_spec() = {Name :: string(), mod_args()}
309 Defines a subsystem in the daemon.
311 The subsystem_name is the name that a client requests to start
313 with for example ssh_connection:subsystem/4.
314 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 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 shell_daemon_option() = {shell, shell_spec()}
326 shell_spec() = mod_fun_args() | shell_fun() | disabled
328 shell_fun() = 'shell_fun/1'() | 'shell_fun/2'()
330 'shell_fun/1'() = fun((User :: string()) -> pid())
332 'shell_fun/2'() =
334 fun((User :: string(), PeerAddr :: inet:ip_address()) -> pid())
335 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 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 exec_daemon_option() = {exec, exec_spec()}
345 exec_spec() =
347 {direct, exec_fun()} | disabled | deprecated_exec_opt()
348 exec_fun() = 'exec_fun/1'() | 'exec_fun/2'() | 'exec_fun/3'()
350 'exec_fun/1'() = fun((Cmd :: string()) -> exec_result())
352 'exec_fun/2'() =
354 fun((Cmd :: string(), User :: string()) -> exec_result())
355 'exec_fun/3'() =
357 fun((Cmd :: string(),
358 User :: string(),
359 ClientAddr :: ip_port()) ->
360 exec_result())
361 exec_result() =
363 {ok, Result :: term()} | {error, Reason :: term()}
364 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 See the User's Guide section on One-Time Execution for examples.
371 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 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 The option cooperates with the daemon-option shell in the fol‐
388 lowing way:
389 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 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 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 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 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 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 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 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 deprecated_exec_opt() = function() | mod_fun_args()
436 Old-style exec specification that are kept for compatibility,
438 but should not be used in new programs
439 ssh_cli_daemon_option() = {ssh_cli, mod_args() | no_cli}
441 Provides your own CLI implementation in a daemon.
443 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 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 prompt_texts() =
461 kb_int_tuple() | kb_int_fun_3() | kb_int_fun_4()
462 kb_int_tuple() =
464 {Name :: string(),
465 Instruction :: string(),
466 Prompt :: string(),
467 Echo :: boolean()}
468 kb_int_fun_3() =
470 fun((Peer :: ip_port(), User :: string(), Service :: string()) ->
471 kb_int_tuple())
472 kb_int_fun_4() =
474 fun((Peer :: ip_port(),
475 User :: string(),
476 Service :: string(),
477 State :: any()) ->
478 kb_int_tuple())
479 pwdfun_2() =
481 fun((User :: string(), Password :: string() | pubkey) ->
482 boolean())
483 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 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 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 The parameter Echo guides the client about need to hide the
503 password.
504 The default value is: {auth_method_kb_interactive_data,
506 {"SSH server", "Enter password for \""++User++"\"", "pass‐
507 word: ", false}>
508 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 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 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 The term "user" is used differently in OpenSSH and SSH in
528 Erlang/OTP: see more in the User's Guide.
529 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 In case of a pwdfun checking the user, the atom pubkey is
535 put in the password argument.
536 password:
538 Provides a global password that authenticates any user.
539 Warning:
541 Intended to facilitate testing.
542 From a security perspective this option makes the server very
544 vulnerable.
545 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 This fun can also be used to make delays in authentication
553 tries for example by calling timer:sleep/1.
554 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 The fun should return:
561 * true if the user and password is valid
563 * false if the user or password is invalid
565 * 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 * {true, NewState:any()} if the user and password is valid
571 * {false, NewState:any()} if the user or password is invalid
573 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 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 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 * true if the user and password is valid
588 * false if the user or password is invalid
590 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 This variant is kept for compatibility.
597 no_auth_needed:
599 If true, a client is authenticated without any need of pro‐
600 viding any password or key.
601 This option is only intended for very special applications
603 due to the high risk of accepting any connecting client.
604 The default value is false.
606 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 explicit_group() =
615 {Size :: integer() >= 1,
616 G :: integer() >= 1,
617 P :: integer() >= 1}
618 explicit_group_file() = {file, string()}
620 ssh_moduli_file() = {ssh_moduli_file, string()}
622 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 {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 {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 {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 The default list is fetched from the public_key application.
643 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 The default value is {0,infinity}.
651 If MaxUsed < MinUsed in a key exchange, it will fail with a
653 disconnect.
654 See RFC 4419 for the function of the Max and Min values.
656 hello_timeout_daemon_option() = {hello_timeout, timeout()}
658 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 For more information about timeouts, see the Timeouts section
665 in the User's Guide Hardening chapter.
666 negotiation_timeout_daemon_option() =
668 {negotiation_timeout, timeout()}
669 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 For more information about timeouts, see the Timeouts section
675 in the User's Guide Hardening chapter.
676 max_initial_idle_time_daemon_option() =
678 {max_initial_idle_time, timeout()}
679 Maximum time in milliseconds for the first channel start after
681 completion of the authentication negotiation. Defaults to infin‐
682 ity.
683 For more information about timeouts, see the Timeouts section
685 in the User's Guide Hardening chapter.
686 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 For more information about hardening, see the Hardening section
694 in the User's Guide chapter.
695 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 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 Notice that if parallel_login is false, only one client at a
711 time can be in the authentication phase.
712 By default, this option is not set. This means that the num‐
714 ber is not limited.
715 max_channels:
717 The maximum number of channels with active remote subsystem
718 that are accepted for each connection to this daemon
719 By default, this option is not set. This means that the num‐
721 ber is not limited.
722 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 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 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 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 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 connectfun:
758 Provides a fun to implement your own logging when a user au‐
759 thenticates to the server.
760 failfun:
762 Provides a fun to implement your own logging when a user
763 fails to authenticate.
764 send_ext_info_daemon_option() = {send_ext_info, boolean()}
766 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 Default value is true which is compatible with other implementa‐
773 tions not supporting ext-info.
774 tcpip_tunnel_in_daemon_option() = {tcpip_tunnel_in, boolean()}
776 Enables (true) or disables (false) the possibility to tunnel a
778 TCP/IP connection in to a server. Disabled per default.
779 tcpip_tunnel_out_daemon_option() =
781 {tcpip_tunnel_out, boolean()}
782 Enables (true) or disables (false) the possibility to tunnel a
784 TCP/IP connection out of a server. Disabled per default.
785 Options common to clients and daemons
787 common_options() = [common_option()]
788 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 The options above can be used both in clients and in daemons
808 (servers). They are further explained below.
809 profile_common_option() = {profile, atom()}
811 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 max_idle_time_common_option() = {idle_time, timeout()}
820 Sets a time-out on a connection when no channels are open. De‐
822 faults to infinity. The unit is milliseconds.
823 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 For more information about timeouts, see the Timeouts section
829 in the User's Guide Hardening chapter.
830 max_log_item_len_common_option() =
832 {max_log_item_len, limit_bytes()}
833 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 rekey_limit_common_option() =
838 {rekey_limit,
839 Bytes ::
840 limit_bytes() |
841 {Minutes :: limit_time(), Bytes :: limit_bytes()}}
842 limit_bytes() = integer() >= 0 | infinity
844 limit_time() = integer() >= 1 | infinity
846 Sets the limit when rekeying is to be initiated. Both the max
848 time and max amount of data could be configured:
849 * {Minutes, Bytes} initiate rekeying when any of the limits
851 are reached.
852 * Bytes initiate rekeying when Bytes number of bytes are
854 transferred, or at latest after one hour.
855 When a rekeying is done, both the timer and the byte counter are
857 restarted. Defaults to one hour and one GByte.
858 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 key_cb_common_option() =
867 {key_cb,
868 Module :: atom() | {Module :: atom(), Opts :: [term()]}}
869 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 The Opts defaults to [] when only the Module is specified.
877 The default value of this option is {ssh_file, []}. See also the
879 manpage of ssh_file.
880 A call to the call-back function F will be
882 Module:F(..., [{key_cb_private,Opts}|UserOptions])
884 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 pref_public_key_algs_common_option() =
891 {pref_public_key_algs, [pubkey_alg()]}
892 List of user (client) public key algorithms to try to use.
894 The default value is the public_key entry in the list returned
896 by ssh:default_algorithms/0.
897 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 See also the option user_dir for specifying the path to the
904 user's keys.
905 disconnectfun_common_option() =
907 {disconnectfun, fun((Reason :: term()) -> void | any())}
908 Provides a fun to implement your own logging or other handling
910 at disconnects.
911 unexpectedfun_common_option() =
913 {unexpectedfun,
914 fun((Message :: term(), {Host :: term(), Port :: term()}) ->
915 report | skip)}
916 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 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 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 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 id_string_common_option() =
942 {id_string,
943 string() |
944 random |
945 {random, Nmin :: integer() >= 1, Nmax :: integer() >= 1}}
946 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 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 The value {random, Nmin, Nmax} will make a random string with at
956 least Nmin characters and at most Nmax characters.
957 preferred_algorithms_common_option() =
959 {preferred_algorithms, algs_list()}
960 algs_list() = [alg_entry()]
962 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 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 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 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 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 compression_alg() = none | zlib | 'zlib@openssh.com'
1000 double_algs(AlgType) =
1002 [{client2server, [AlgType]} | {server2client, [AlgType]}] |
1003 [AlgType]
1004 List of algorithms to use in the algorithm negotiation. The de‐
1006 fault algs_list() can be obtained from default_algorithms/0.
1007 If an alg_entry() is missing in the algs_list(), the default
1009 value is used for that entry.
1010 Here is an example of this option:
1012 {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 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 For background and more examples see the User's Guide.
1029 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 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 modify_algorithms_common_option() =
1041 {modify_algorithms, modify_algs_list()}
1042 modify_algs_list() =
1044 [{append, algs_list()} |
1045 {prepend, algs_list()} |
1046 {rm, algs_list()}]
1047 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 The algorithm for modifications works like this:
1053 * 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 * The head of the modify_algs_list() modifies A giving the re‐
1059 sult A'.
1060 The possible modifications are:
1062 * 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 * Remove (rm) one or more algorithms from A.
1069 * Repeat the modification step with the tail of mod‐
1071 ify_algs_list() and the resulting A'.
1072 If an unsupported algorithm is in the modify_algs_list(), it
1074 will be silently ignored
1075 If there are more than one modify_algorithms options, the result
1077 is undefined.
1078 Here is an example of this option:
1080 {modify_algorithms,
1082 [{prepend, [{kex, ['diffie-hellman-group1-sha1']}],
1083 {rm, [{compression, [none]}]}
1084 ]
1085 }
1086 The example specifies that:
1089 * 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 * The compression algorithm none (= no compression) is removed
1095 so compression is enforced
1096 For background and more examples see the User's Guide.
1098 inet_common_option() = {inet, inet | inet6}
1100 IP version to use when the host address is specified as any.
1102 auth_methods_common_option() = {auth_methods, string()}
1104 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 Note that the client is free to use any order and to exclude
1110 methods.
1111 fd_common_option() = {fd, gen_tcp:socket()}
1113 Allows an existing file-descriptor to be used (passed on to the
1115 transport protocol).
1116 Other data types
1118 host() = string() | inet:ip_address() | loopback
1119 ip_port() = {inet:ip_address(), inet:port_number()}
1121 mod_args() = {Module :: atom(), Args :: list()}
1123 mod_fun_args() =
1125 {Module :: atom(), Function :: atom(), Args :: list()}
1126 open_socket() = gen_tcp:socket()
1128 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 daemon_ref()
1134 Opaque data type representing a daemon.
1136 Returned by the functions daemon/1,2,3.
1138 connection_ref()
1140 Opaque data type representing a connection between a client and
1142 a server (daemon).
1143 Returned by the functions connect/2,3,4 and ssh_sftp:start_chan‐
1145 nel/2,3.
1146 channel_id()
1148 Opaque data type representing a channel inside a connection.
1150 Returned by the functions ssh_connection:session_channel/2,4.
1152 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 version() = {protocol_version(), software_version()}
1164 protocol_version() =
1166 {Major :: integer() >= 1, Minor :: integer() >= 0}
1167 software_version() = string()
1169 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 conn_info_channels() = [proplists:proplist()]
1183 Return values from the connection_info/1 and connection_info/2
1185 functions.
1186 In the option info tuple are only the options included that dif‐
1188 fers from the default values.
1189 daemon_info_tuple() =
1191 {port, inet:port_number()} |
1192 {ip, inet:ip_address()} |
1193 {profile, atom()} |
1194 {options, daemon_options()}
1195 Return values from the daemon_info/1 and daemon_info/2 func‐
1197 tions.
1198 In the option info tuple are only the options included that dif‐
1200 fers from the default values.
1201 opaque_client_options()
1203 opaque_daemon_options()
1205 opaque_common_options()
1207 Opaque types that define experimental options that are not to be
1209 used in products.
1210
1212 close(ConnectionRef) -> ok | {error, term()}
1213 Types:
1215 ConnectionRef = connection_ref()
1217 Closes an SSH connection.
1219 connect(Host, Port, Options) -> Result
1221 connect(Host, Port, Options, NegotiationTimeout) -> Result
1222 connect(TcpSocket, Options) -> Result
1223 connect(TcpSocket, Options, NegotiationTimeout) -> Result
1224 Types:
1226 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 Connects to an SSH server at the Host on Port.
1235 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 No channel is started. This is done by calling ssh_connec‐
1242 tion:session_channel/[2, 4].
1243 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 connection_info(ConnectionRef) -> InfoTupleList
1249 connection_info(ConnectionRef, Key :: ItemList | Item) ->
1251 InfoTupleList | InfoTuple
1252 Types:
1254 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 Returns information about a connection intended for e.g debug‐
1265 ging or logging.
1266 When the Key is a single Item, the result is a single InfoTuple
1268 set_sock_opts(ConnectionRef, SocketOptions) ->
1270 ok | {error, inet:posix()}
1271 Types:
1273 ConnectionRef = connection_ref()
1275 SocketOptions = [gen_tcp:option()]
1276 Sets tcp socket options on the tcp-socket below an ssh connec‐
1278 tion.
1279 This function calls the inet:setopts/2, read that documentation
1281 and for gen_tcp:option().
1282 All gen_tcp socket options except
1284 * active
1286 * deliver
1288 * mode and
1290 * packet
1292 are allowed. The excluded options are reserved by the SSH appli‐
1294 cation.
1295 Warning:
1297 This is an extremely dangerous function. You use it on your own
1298 risk.
1299 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 Some values may destroy the functionality of the SSH protocol.
1305 get_sock_opts(ConnectionRef, SocketGetOptions) ->
1308 ok | {error, inet:posix()}
1309 Types:
1311 ConnectionRef = connection_ref()
1313 SocketGetOptions = [gen_tcp:option_name()]
1314 Get tcp socket option values of the tcp-socket below an ssh con‐
1316 nection.
1317 This function calls the inet:getopts/2, read that documentation.
1319 daemon(Port | TcpSocket) -> Result
1321 daemon(Port | TcpSocket, Options) -> Result
1322 daemon(HostAddress, Port, Options) -> Result
1323 Types:
1325 Port = integer()
1327 TcpSocket = open_socket()
1328 Options = daemon_options()
1329 HostAddress = host() | any
1330 Result = {ok, daemon_ref()} | {error, atom()}
1331 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 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 For a description of the options, see Daemon Options.
1342 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 The rules for handling the two address passing options are:
1349 * if HostAddress is an IP-address, that IP-address is the lis‐
1351 tening address. An 'ip'-option will be discarded if present.
1352 * 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 * 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 * if HostAddress is any and an 'ip'-option is present, the
1363 listening address is set to the value of the 'ip'-option
1364 daemon_replace_options(DaemonRef, NewUserOptions) ->
1366 {ok, daemon_ref()} | {error, term()}
1367 Types:
1369 DaemonRef = daemon_ref()
1371 NewUserOptions = daemon_options()
1372 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 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 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 daemon_info(DaemonRef) ->
1388 {ok, InfoTupleList} | {error, bad_daemon_ref}
1389 daemon_info(DaemonRef, Key :: ItemList | Item) ->
1391 InfoTupleList | InfoTuple | {error, bad_daemon_ref}
1392 Types:
1394 DaemonRef = daemon_ref()
1396 ItemList = [Item]
1397 Item = ip | port | profile | options
1398 InfoTupleList = [InfoTuple]
1399 InfoTuple = daemon_info_tuple()
1400 Returns information about a daemon intended for e.g debugging or
1402 logging.
1403 When the Key is a single Item, the result is a single InfoTuple
1405 Note that daemon_info/1 and daemon_info/2 returns different
1407 types due to compatibility reasons.
1408 default_algorithms() -> algs_list()
1410 Returns a key-value list, where the keys are the different types
1412 of algorithms and the values are the algorithms themselves.
1413 See the User's Guide for an example.
1415 shell(Host | TcpSocket) -> Result
1417 shell(Host | TcpSocket, Options) -> Result
1418 shell(Host, Port, Options) -> Result
1419 Types:
1421 Host = host()
1423 TcpSocket = open_socket()
1424 Port = inet:port_number()
1425 Options = client_options()
1426 Result = ok | {error, Reason::term()}
1427 Connects to an SSH server at Host and Port (defaults to 22) and
1429 starts an interactive shell on that remote host.
1430 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 For a description of the options, see Client Options.
1437 The function waits for user input, and does not return until the
1439 remote shell is ended (that is, exit from the shell).
1440 start() -> ok | {error, term()}
1442 start(Type) -> ok | {error, term()}
1444 Types:
1446 Type = permanent | transient | temporary
1448 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 stop() -> ok | {error, term()}
1454 Stops the ssh application. For more information, see the appli‐
1456 cation(3) manual page in Kernel.
1457 stop_daemon(DaemonRef :: daemon_ref()) -> ok
1459 stop_daemon(Address :: inet:ip_address(),
1461 Port :: inet:port_number()) ->
1462 ok
1463 stop_daemon(Address :: any | inet:ip_address(),
1465 Port :: inet:port_number(),
1466 Profile :: atom()) ->
1467 ok
1468 Stops the listener and all connections started by the listener.
1470 stop_listener(SysSup :: daemon_ref()) -> ok
1472 stop_listener(Address :: inet:ip_address(),
1474 Port :: inet:port_number()) ->
1475 ok
1476 stop_listener(Address :: any | inet:ip_address(),
1478 Port :: inet:port_number(),
1479 Profile :: term()) ->
1480 ok
1481 Stops the listener, but leaves existing connections started by
1483 the listener operational.
1484 tcpip_tunnel_from_server(ConnectionRef, ListenHost, ListenPort,
1486 ConnectToHost, ConnectToPort) ->
1487 {ok, TrueListenPort} | {error, term()}
1488 tcpip_tunnel_from_server(ConnectionRef, ListenHost, ListenPort,
1490 ConnectToHost, ConnectToPort, Timeout) ->
1491 {ok, TrueListenPort} | {error, term()}
1492 Types:
1494 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 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 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 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 tcpip_tunnel_to_server(ConnectionRef, ListenHost, ListenPort,
1518 ConnectToHost, ConnectToPort) ->
1519 {ok, TrueListenPort} | {error, term()}
1520 tcpip_tunnel_to_server(ConnectionRef, ListenHost, ListenPort,
1522 ConnectToHost, ConnectToPort, Timeout) ->
1523 {ok, TrueListenPort} | {error, term()}
1524 Types:
1526 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 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 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 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 hostkey_fingerprint(HostKey) -> string()
1549 hostkey_fingerprint(DigestType, HostKey) -> string()
1550 hostkey_fingerprint([DigestType], HostKey) -> [string()]
1551 Types:
1553 HostKey = public_key:public_key()
1555 DigestType = public_key:digest_type()
1556 Calculates a ssh fingerprint from a public host key as openssh
1558 does.
1559 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 Examples:
1566 2> ssh:hostkey_fingerprint(Key).
1568 "f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"
1569 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 4> ssh:hostkey_fingerprint(sha,Key).
1574 "SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY"
1575 5> ssh:hostkey_fingerprint(sha256,Key).
1577 "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"
1578 6> ssh:hostkey_fingerprint([sha,sha256],Key).
1580 ["SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY",
1581 "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"]
1582Ericsson AB ssh 5.0.1 ssh(3)