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. Thoose 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
34 option 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. Similarily,
38 to just open an sftp (file transfer) connection to a remote machine,
39 the simplest way is to use ssh_sftp:start_channel/1,2,3.
40 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
50 explaining 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 Thoose objects are per default stored in files. The default names,
59 paths and file formats are the same as for OpenSSH. Keys could be gen‐
60 erated 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 completly different storage could be interfaced by writing call-back
65 modules using the behaviours ssh_client_key_api and/or
66 ssh_server_key_api. A callback module is installed with the option
67 key_cb to the client and/or the daemon.
68 Daemons
70 The keys are by default stored in files:
71 * Mandatory: one or more Host key(s) , both private and public.
73 Default 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
85 authorization. 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
92 directory .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
129 explained below or by following the hyperlinks.
130 host_accepting_client_options() =
132 {silently_accept_hosts, accept_hosts()} |
133 {user_interaction, boolean()} |
134 {save_accepted_host, boolean()} |
135 {quiet_mode, boolean()}
136 accept_hosts() =
138 boolean() |
139 accept_callback() |
140 {HashAlgoSpec :: fp_digest_alg(), accept_callback()}
141 fp_digest_alg() = md5 | crypto:sha1() | crypto:sha2()
143 accept_callback() =
145 fun((PeerName :: string(), fingerprint()) -> boolean())
146 fingerprint() = string() | [string()]
148 silently_accept_hosts:
150 This option guides the connect function on how to act when
151 the connected server presents a Host Key that the client has
152 not seen before. The default is to ask the user with a ques‐
153 tion on stdio of whether to accept or reject the new Host
154 Key. See the option user_dir for specifying the path to the
155 file known_hosts where previously accepted Host Keys are
156 recorded. See also the option key_cb for the general way to
157 handle keys.
158 The option can be given in three different forms as seen
160 above:
161 * The value is a boolean(). The value true will make the
163 client accept any unknown Host Key without any user inter‐
164 action. The value false preserves the default behaviour of
165 asking the user on stdio.
166 * An accept_callback() will be called and the boolean return
168 value true will make the client accept the Host Key. A
169 return value of false will make the client to reject the
170 Host Key and as a result the connection will be closed.
171 The arguments to the fun are:
172 * PeerName - a string with the name or address of the
174 remote host.
175 * FingerPrint - the fingerprint of the Host Key as pub‐
177 lic_key:ssh_hostkey_fingerprint/1 calculates it.
178 * A tuple {HashAlgoSpec, accept_callback}. The HashAlgoSpec
180 specifies which hash algorithm shall be used to calculate
181 the fingerprint used in the call of the accept_callback().
182 The HashALgoSpec is either an atom or a list of atoms as
183 the first argument in public_key:ssh_hostkey_finger‐
184 print/2. If it is a list of hash algorithm names, the Fin‐
185 gerPrint argument in the accept_callback() will be a list
186 of fingerprints in the same order as the corresponding
187 name in the HashAlgoSpec list.
188 user_interaction:
190 If false, disables the client to connect to the server if
191 any user interaction is needed, such as accepting the server
192 to be added to the known_hosts file, or supplying a pass‐
193 word.
194 Even if user interaction is allowed it can be suppressed by
196 other options, such as silently_accept_hosts and password.
197 However, those options are not always desirable to use from
198 a security point of view.
199 Defaults to true.
201 save_accepted_host:
203 If true, the client saves an accepted host key to avoid the
204 accept question the next time the same host is connected. If
205 the option key_cb is not present, the key is saved in the
206 file "known_hosts". See option user_dir for the location of
207 that file.
208 If false, the key is not saved and the key will still be
210 unknown at the next access of the same host.
211 Defaults to true
213 quiet_mode:
215 If true, the client does not print anything on authoriza‐
216 tion.
217 Defaults to false
219 authentication_client_options() =
221 {user, string()} | {password, string()}
222 user:
224 Provides the username. If this option is not given, ssh
225 reads from the environment (LOGNAME or USER on UNIX, USER‐
226 NAME on Windows).
227 password:
229 Provides a password for password authentication. If this
230 option is not given, the user is asked for a password, if
231 the password authentication method is attempted.
232 diffie_hellman_group_exchange_client_option() =
234 {dh_gex_limits,
235 {Min :: integer() >= 1,
236 I :: integer() >= 1,
237 Max :: integer() >= 1}}
238 Sets the three diffie-hellman-group-exchange parameters that
240 guides the connected server in choosing a group. See RFC 4419
241 for the details. The default value is {1024, 6144, 8192}.
242 connect_timeout_client_option() = {connect_timeout, timeout()}
244 Sets a timeout on the transport layer connect time. For gen_tcp
246 the time is in milli-seconds and the default value is infinity.
247 See the parameter Timeout in connect/4 for a timeout of the
249 negotiation phase.
250 recv_ext_info_client_option() = {recv_ext_info, boolean()}
252 Make the client tell the server that the client accepts exten‐
254 sion negotiation, that is, include ext-info-c in the kexinit
255 message sent. See RFC 8308 for details and ssh(6) for a list of
256 currently implemented extensions.
257 Default value is true which is compatible with other implementa‐
259 tions not supporting ext-info.
260 Daemon Options (Server Options)
262 daemon_options() = [daemon_option()]
263 daemon_option() =
265 subsystem_daemon_option() |
266 shell_daemon_option() |
267 exec_daemon_option() |
268 ssh_cli_daemon_option() |
269 authentication_daemon_options() |
270 diffie_hellman_group_exchange_daemon_option() |
271 negotiation_timeout_daemon_option() |
272 hardening_daemon_options() |
273 callbacks_daemon_options() |
274 send_ext_info_daemon_option() |
275 opaque_daemon_options() |
276 gen_tcp:listen_option() |
277 common_option()
278 Options for daemons. The individual options are further
280 explained below or by following the hyperlinks.
281 subsystem_daemon_option() = {subsystems, subsystem_spec()}
283 subsystem_spec() = {Name :: string(), mod_args()}
285 Defines a subsystem in the daemon.
287 The subsystem_name is the name that a client requests to start
289 with for example ssh_connection:subsystem/4.
290 The channel_callback is the module that implements the
292 ssh_server_channel (replaces ssh_daemon_channel) behaviour in
293 the daemon. See the section Creating a Subsystem in the User's
294 Guide for more information and an example.
295 If the subsystems option is not present, the value of
297 ssh_sftpd:subsystem_spec([]) is used. This enables the sftp sub‐
298 system by default. The option can be set to the empty list if
299 you do not want the daemon to run any subsystems.
300 shell_daemon_option() =
302 {shell, mod_fun_args() | 'shell_fun/1'() | 'shell_fun/2'()}
303 'shell_fun/1'() = fun((User :: string()) -> pid())
305 'shell_fun/2'() =
307 fun((User :: string(), PeerAddr :: inet:ip_address()) -> pid())
308 Defines the read-eval-print loop used in a daemon when a shell
310 is requested by the client. The default is to use the Erlang
311 shell: {shell, start, []}
312 See the option exec for a description of how the daemon execute
314 exec-requests depending on the shell- and exec-options.
315 exec_daemon_option() = {exec, exec_spec()}
317 exec_spec() = {direct, exec_fun()}
319 exec_fun() = 'exec_fun/1'() | 'exec_fun/2'() | 'exec_fun/3'()
321 'exec_fun/1'() = fun((Cmd :: string()) -> exec_result())
323 'exec_fun/2'() =
325 fun((Cmd :: string(), User :: string()) -> exec_result())
326 'exec_fun/3'() =
328 fun((Cmd :: string(),
329 User :: string(),
330 ClientAddr :: ip_port()) ->
331 exec_result())
332 exec_result() =
334 {ok, Result :: term()} | {error, Reason :: term()}
335 This option changes how the daemon execute exec-requests from
337 clients. The term in the return value is formatted to a string
338 if it is a non-string type. No trailing newline is added in the
339 ok-case but in the error case.
340 Error texts are returned on channel-type 1 which usually is
342 piped to stderr on e.g Linux systems. Texts from a successful
343 execution will in similar manner be piped to stdout. The exit-
344 status code is set to 0 for success and -1 for errors. The exact
345 results presented on the client side depends on the client and
346 the client's operating system.
347 The option cooperates with the daemon-option shell in the fol‐
349 lowing way:
350 1. If the exec-option is present (the shell-option may or may
352 not be present)::
353 The exec-option fun is called with the same number of param‐
354 eters as the arity of the fun, and the result is returned to
355 the client.
356 2. If the exec-option is absent, but a shell-option is present
358 with the default Erlang shell::
359 The default Erlang evaluator is used and the result is
360 returned to the client.
361 3. If the exec-option is absent, but a shell-option is present
363 that is not the default Erlang shell::
364 The exec-request is not evaluated and an error message is
365 returned to the client.
366 4. If neither the exec-option nor the shell-option is
368 present::
369 The default Erlang evaluator is used and the result is
370 returned to the client.
371 If a custom CLI is installed (see the option ssh_cli) the rules
373 above are replaced by thoose implied by the custom CLI.
374 Note:
376 The exec-option has existed for a long time but has not previ‐
377 ously been documented. The old definition and behaviour are
378 retained but obey the rules 1-4 above if conflicting. The old
379 and undocumented style should not be used in new programs.
380 ssh_cli_daemon_option() = {ssh_cli, mod_args() | no_cli}
383 Provides your own CLI implementation in a daemon.
385 It is a channel callback module that implements a shell and com‐
387 mand execution. The shell's read-eval-print loop can be custom‐
388 ized, using the option shell. This means less work than imple‐
389 menting an own CLI channel. If ssh_cli is set to no_cli, the CLI
390 channels like shell and exec are disabled and only subsystem
391 channels are allowed.
392 authentication_daemon_options() =
394 ssh_file:system_dir_daemon_option() |
395 {auth_method_kb_interactive_data, prompt_texts()} |
396 {user_passwords, [{UserName :: string(), Pwd :: string()}]} |
397 {password, string()} |
398 {pwdfun, pwdfun_2() | pwdfun_4()}
399 prompt_texts() = kb_int_tuple() | kb_int_fun_3()
401 kb_int_tuple() =
403 {Name :: string(),
404 Instruction :: string(),
405 Prompt :: string(),
406 Echo :: boolean()}
407 kb_int_fun_3() =
409 fun((Peer :: ip_port(), User :: string(), Service :: string()) ->
410 kb_int_tuple())
411 pwdfun_2() =
413 fun((User :: string(), Password :: string()) -> boolean())
414 pwdfun_4() =
416 fun((User :: string(),
417 Password :: string(),
418 PeerAddress :: ip_port(),
419 State :: any()) ->
420 boolean() |
421 disconnect |
422 {boolean(), NewState :: any()})
423 auth_method_kb_interactive_data:
425 Sets the text strings that the daemon sends to the client
426 for presentation to the user when using keyboard-interactive
427 authentication.
428 If the fun/3 is used, it is called when the actual authenti‐
430 cation occurs and may therefore return dynamic data like
431 time, remote ip etc.
432 The parameter Echo guides the client about need to hide the
434 password.
435 The default value is: {auth_method_kb_interactive_data,
437 {"SSH server", "Enter password for \""++User++"\"", "pass‐
438 word: ", false}>
439 user_passwords:
441 Provides passwords for password authentication. The pass‐
442 words are used when someone tries to connect to the server
443 and public key user-authentication fails. The option pro‐
444 vides a list of valid usernames and the corresponding pass‐
445 words.
446 password:
448 Provides a global password that authenticates any user.
449 Warning:
451 Intended to facilitate testing.
452 From a security perspective this option makes the server very
454 vulnerable.
455 pwdfun with pwdfun_4():
458 Provides a function for password validation. This could used
459 for calling an external system or handeling passwords stored
460 as hash values.
461 This fun can also be used to make delays in authentication
463 tries for example by calling timer:sleep/1.
464 To facilitate for instance counting of failed tries, the
466 State variable could be used. This state is per connection
467 only. The first time the pwdfun is called for a connection,
468 the State variable has the value undefined.
469 The fun should return:
471 * true if the user and password is valid
473 * false if the user or password is invalid
475 * disconnect if a SSH_MSG_DISCONNECT message should be sent
477 immediately. It will be followed by a close of the under‐
478 lying tcp connection.
479 * {true, NewState:any()} if the user and password is valid
481 * {false, NewState:any()} if the user or password is invalid
483 A third usage is to block login attempts from a missbehaving
485 peer. The State described above can be used for this. The
486 return value disconnect is useful for this.
487 pwdfun with pwdfun_2():
489 Provides a function for password validation. This function
490 is called with user and password as strings, and returns:
491 * true if the user and password is valid
493 * false if the user or password is invalid
495 This variant is kept for compatibility.
497 diffie_hellman_group_exchange_daemon_option() =
499 {dh_gex_groups,
500 [explicit_group()] |
501 explicit_group_file() |
502 ssh_moduli_file()} |
503 {dh_gex_limits, {Min :: integer() >= 1, Max :: integer() >= 1}}
504 explicit_group() =
506 {Size :: integer() >= 1,
507 G :: integer() >= 1,
508 P :: integer() >= 1}
509 explicit_group_file() = {file, string()}
511 ssh_moduli_file() = {ssh_moduli_file, string()}
513 dh_gex_groups:
515 Defines the groups the server may choose among when diffie-
516 hellman-group-exchange is negotiated. See RFC 4419 for
517 details. The three variants of this option are:
518 {Size=integer(),G=integer(),P=integer()}:
520 The groups are given explicitly in this list. There may be
521 several elements with the same Size. In such a case, the
522 server will choose one randomly in the negotiated Size.
523 {file,filename()}:
525 The file must have one or more three-tuples {Size=inte‐
526 ger(),G=integer(),P=integer()} terminated by a dot. The
527 file is read when the daemon starts.
528 {ssh_moduli_file,filename()}:
530 The file must be in ssh-keygen moduli file format. The
531 file is read when the daemon starts.
532 The default list is fetched from the public_key application.
534 dh_gex_limits:
536 Limits what a client can ask for in diffie-hellman-group-
537 exchange. The limits will be {MaxUsed = min(MaxClient,Max),
538 MinUsed = max(MinClient,Min)} where MaxClient and MinClient
539 are the values proposed by a connecting client.
540 The default value is {0,infinity}.
542 If MaxUsed < MinUsed in a key exchange, it will fail with a
544 disconnect.
545 See RFC 4419 for the function of the Max and Min values.
547 negotiation_timeout_daemon_option() =
549 {negotiation_timeout, timeout()}
550 Maximum time in milliseconds for the authentication negotiation.
552 Defaults to 120000 ms (2 minutes). If the client fails to log in
553 within this time, the connection is closed.
554 hardening_daemon_options() =
556 {max_sessions, integer() >= 1} |
557 {max_channels, integer() >= 1} |
558 {parallel_login, boolean()} |
559 {minimal_remote_max_packet_size, integer() >= 1}
560 max_sessions:
562 The maximum number of simultaneous sessions that are
563 accepted at any time for this daemon. This includes sessions
564 that are being authorized. Thus, if set to N, and N clients
565 have connected but not started the login process, connection
566 attempt N+1 is aborted. If N connections are authenticated
567 and still logged in, no more logins are accepted until one
568 of the existing ones log out.
569 The counter is per listening port. Thus, if two daemons are
571 started, one with {max_sessions,N} and the other with
572 {max_sessions,M}, in total N+M connections are accepted for
573 the whole ssh application.
574 Notice that if parallel_login is false, only one client at a
576 time can be in the authentication phase.
577 By default, this option is not set. This means that the num‐
579 ber is not limited.
580 max_channels:
582 The maximum number of channels with active remote subsystem
583 that are accepted for each connection to this daemon
584 By default, this option is not set. This means that the num‐
586 ber is not limited.
587 parallel_login:
589 If set to false (the default value), only one login is han‐
590 dled at a time. If set to true, an unlimited number of login
591 attempts are allowed simultaneously.
592 If the max_sessions option is set to N and parallel_login is
594 set to true, the maximum number of simultaneous login
595 attempts at any time is limited to N-K, where K is the num‐
596 ber of authenticated connections present at this daemon.
597 Warning:
599 Do not enable parallel_logins without protecting the server by
600 other means, for example, by the max_sessions option or a
601 firewall configuration. If set to true, there is no protection
602 against DOS attacks.
603 minimal_remote_max_packet_size:
606 The least maximum packet size that the daemon will accept in
607 channel open requests from the client. The default value is
608 0.
609 callbacks_daemon_options() =
611 {failfun,
612 fun((User :: string(),
613 PeerAddress :: inet:ip_address(),
614 Reason :: term()) ->
615 term())} |
616 {connectfun,
617 fun((User :: string(),
618 PeerAddress :: inet:ip_address(),
619 Method :: string()) ->
620 term())}
621 connectfun:
623 Provides a fun to implement your own logging when a user
624 authenticates to the server.
625 failfun:
627 Provides a fun to implement your own logging when a user
628 fails to authenticate.
629 send_ext_info_daemon_option() = {send_ext_info, boolean()}
631 Make the server (daemon) tell the client that the server accepts
633 extension negotiation, that is, include ext-info-s in the kex‐
634 init message sent. See RFC 8308 for details and ssh(6) for a
635 list of currently implemented extensions.
636 Default value is true which is compatible with other implementa‐
638 tions not supporting ext-info.
639 Options common to clients and daemons
641 common_options() = [common_option()]
642 common_option() =
644 ssh_file:user_dir_common_option() |
645 profile_common_option() |
646 max_idle_time_common_option() |
647 key_cb_common_option() |
648 disconnectfun_common_option() |
649 unexpectedfun_common_option() |
650 ssh_msg_debug_fun_common_option() |
651 rekey_limit_common_option() |
652 id_string_common_option() |
653 pref_public_key_algs_common_option() |
654 preferred_algorithms_common_option() |
655 modify_algorithms_common_option() |
656 auth_methods_common_option() |
657 inet_common_option() |
658 fd_common_option()
659 The options above can be used both in clients and in daemons
661 (servers). They are further explained below.
662 profile_common_option() = {profile, atom()}
664 Used together with ip-address and port to uniquely identify a
666 ssh daemon. This can be useful in a virtualized environment,
667 where there can be more that one server that has the same ip-
668 address and port. If this property is not explicitly set, it is
669 assumed that the the ip-address and port uniquely identifies the
670 SSH daemon.
671 max_idle_time_common_option() = {idle_time, timeout()}
673 Sets a time-out on a connection when no channels are active.
675 Defaults to infinity.
676 rekey_limit_common_option() =
678 {rekey_limit,
679 Bytes ::
680 limit_bytes() |
681 {Minutes :: limit_time(), Bytes :: limit_bytes()}}
682 limit_bytes() = integer() >= 0 | infinity
684 limit_time() = integer() >= 1 | infinity
686 Sets the limit when rekeying is to be initiated. Both the max
688 time and max amount of data could be configured:
689 * {Minutes, Bytes} initiate rekeying when any of the limits
691 are reached.
692 * Bytes initiate rekeying when Bytes number of bytes are
694 transferred, or at latest after one hour.
695 When a rekeying is done, both the timer and the byte counter are
697 restarted. Defaults to one hour and one GByte.
698 If Minutes is set to infinity, no rekeying will ever occur due
700 to that max time has passed. Setting Bytes to infinity will
701 inhibit rekeying after a certain amount of data has been trans‐
702 ferred. If the option value is set to {infinity, infinity}, no
703 rekeying will be initiated. Note that rekeying initiated by the
704 peer will still be performed.
705 key_cb_common_option() =
707 {key_cb,
708 Module :: atom() | {Module :: atom(), Opts :: [term()]}}
709 Module implementing the behaviour ssh_client_key_api and/or
711 ssh_server_key_api. Can be used to customize the handling of
712 public keys. If callback options are provided along with the
713 module name, they are made available to the callback module via
714 the options passed to it under the key 'key_cb_private'.
715 The Opts defaults to [] when only the Module is specified.
717 The default value of this option is {ssh_file, []}. See also the
719 manpage of ssh_file.
720 A call to the call-back function F will be
722 Module:F(..., [{key_cb_private,Opts}|UserOptions])
724 where ... are arguments to F as in ssh_client_key_api and/or
727 ssh_server_key_api. The UserOptions are the options given to
728 ssh:connect, ssh:shell or ssh:daemon.
729 pref_public_key_algs_common_option() =
731 {pref_public_key_algs, [pubkey_alg()]}
732 List of user (client) public key algorithms to try to use.
734 The default value is the public_key entry in the list returned
736 by ssh:default_algorithms/0.
737 If there is no public key of a specified type available, the
739 corresponding entry is ignored. Note that the available set is
740 dependent on the underlying cryptolib and current user's public
741 keys.
742 See also the option user_dir for specifying the path to the
744 user's keys.
745 disconnectfun_common_option() =
747 {disconnectfun, fun((Reason :: term()) -> void | any())}
748 Provides a fun to implement your own logging when the peer dis‐
750 connects.
751 unexpectedfun_common_option() =
753 {unexpectedfun,
754 fun((Message :: term(), {Host :: term(), Port :: term()}) ->
755 report | skip)}
756 Provides a fun to implement your own logging or other action
758 when an unexpected message arrives. If the fun returns report
759 the usual info report is issued but if skip is returned no
760 report is generated.
761 ssh_msg_debug_fun_common_option() =
763 {ssh_msg_debug_fun,
764 fun((ssh:connection_ref(),
765 AlwaysDisplay :: boolean(),
766 Msg :: binary(),
767 LanguageTag :: binary()) ->
768 any())}
769 Provide a fun to implement your own logging of the SSH message
771 SSH_MSG_DEBUG. The last three parameters are from the message,
772 see RFC 4253, section 11.3. The connection_ref() is the refer‐
773 ence to the connection on which the message arrived. The return
774 value from the fun is not checked.
775 The default behaviour is ignore the message. To get a printout
777 for each message with AlwaysDisplay = true, use for example
778 {ssh_msg_debug_fun, fun(_,true,M,_)-> io:format("DEBUG: ~p~n",
779 [M]) end}
780 id_string_common_option() =
782 {id_string,
783 string() |
784 random |
785 {random, Nmin :: integer() >= 1, Nmax :: integer() >= 1}}
786 The string the daemon will present to a connecting peer ini‐
788 tially. The default value is "Erlang/VSN" where VSN is the ssh
789 application version number.
790 The value random will cause a random string to be created at
792 each connection attempt. This is to make it a bit more difficult
793 for a malicious peer to find the ssh software brand and version.
794 The value {random, Nmin, Nmax} will make a random string with at
796 least Nmin characters and at most Nmax characters.
797 preferred_algorithms_common_option() =
799 {preferred_algorithms, algs_list()}
800 algs_list() = [alg_entry()]
802 alg_entry() =
804 {kex, [kex_alg()]} |
805 {public_key, [pubkey_alg()]} |
806 {cipher, double_algs(cipher_alg())} |
807 {mac, double_algs(mac_alg())} |
808 {compression, double_algs(compression_alg())}
809 kex_alg() =
811 'diffie-hellman-group-exchange-sha1' |
812 'diffie-hellman-group-exchange-sha256' |
813 'diffie-hellman-group1-sha1' |
814 'diffie-hellman-group14-sha1' |
815 'diffie-hellman-group14-sha256' |
816 'diffie-hellman-group16-sha512' |
817 'diffie-hellman-group18-sha512' |
818 'curve25519-sha256' |
819 'curve25519-sha256@libssh.org' |
820 'curve448-sha512' |
821 'ecdh-sha2-nistp256' |
822 'ecdh-sha2-nistp384' |
823 'ecdh-sha2-nistp521'
824 pubkey_alg() =
826 'ecdsa-sha2-nistp256' |
827 'ecdsa-sha2-nistp384' |
828 'ecdsa-sha2-nistp521' |
829 'ssh-ed25519' |
830 'ssh-ed448' |
831 'rsa-sha2-256' |
832 'rsa-sha2-512' |
833 'ssh-dss' |
834 'ssh-rsa'
835 cipher_alg() =
837 '3des-cbc' |
838 'AEAD_AES_128_GCM' |
839 'AEAD_AES_256_GCM' |
840 'aes128-cbc' |
841 'aes128-ctr' |
842 'aes128-gcm@openssh.com' |
843 'aes192-ctr' |
844 'aes256-ctr' |
845 'aes256-gcm@openssh.com' |
846 'chacha20-poly1305@openssh.com'
847 mac_alg() =
849 'AEAD_AES_128_GCM' |
850 'AEAD_AES_256_GCM' |
851 'hmac-sha1' |
852 'hmac-sha2-256' |
853 'hmac-sha2-512'
854 compression_alg() = none | zlib | 'zlib@openssh.com'
856 double_algs(AlgType) =
858 [{client2server, [AlgType]} | {server2client, [AlgType]}] |
859 [AlgType]
860 List of algorithms to use in the algorithm negotiation. The
862 default algs_list() can be obtained from default_algorithms/0.
863 If an alg_entry() is missing in the algs_list(), the default
865 value is used for that entry.
866 Here is an example of this option:
868 {preferred_algorithms,
870 [{public_key,['ssh-rsa','ssh-dss']},
871 {cipher,[{client2server,['aes128-ctr']},
872 {server2client,['aes128-cbc','3des-cbc']}]},
873 {mac,['hmac-sha2-256','hmac-sha1']},
874 {compression,[none,zlib]}
875 ]
876 }
877 The example specifies different algorithms in the two directions
880 (client2server and server2client), for cipher but specifies the
881 same algorithms for mac and compression in both directions. The
882 kex (key exchange) is implicit but public_key is set explicitly.
883 For background and more examples see the User's Guide.
885 If an algorithm name occurs more than once in a list, the behav‐
887 iour is undefined. The tags in the property lists are also
888 assumed to occur at most one time.
889 Warning:
891 Changing the values can make a connection less secure. Do not
892 change unless you know exactly what you are doing. If you do not
893 understand the values then you are not supposed to change them.
894 modify_algorithms_common_option() =
897 {modify_algorithms, modify_algs_list()}
898 modify_algs_list() =
900 [{append, algs_list()} |
901 {prepend, algs_list()} |
902 {rm, algs_list()}]
903 Modifies the list of algorithms to use in the algorithm negotia‐
905 tion. The modifications are applied after the option pre‐
906 ferred_algorithms (if existing) is applied.
907 The algoritm for modifications works like this:
909 * Input is the modify_algs_list() and a set of algorithms A
911 obtained from the preferred_algorithms option if existing,
912 or else from the ssh:default_algorithms/0.
913 * The head of the modify_algs_list() modifies A giving the
915 result A'.
916 The possible modifications are:
918 * Append or prepend supported but not enabled algorithm(s)
920 to the list of algorithms. If the wanted algorithms
921 already are in A they will first be removed and then
922 appended or prepended,
923 * Remove (rm) one or more algorithms from A.
925 * Repeat the modification step with the tail of mod‐
927 ify_algs_list() and the resulting A'.
928 If an unsupported algorithm is in the modify_algs_list(), it
930 will be silently ignored
931 If there are more than one modify_algorithms options, the result
933 is undefined.
934 Here is an example of this option:
936 {modify_algorithms,
938 [{prepend, [{kex, ['diffie-hellman-group1-sha1']}],
939 {rm, [{compression, [none]}]}
940 ]
941 }
942 The example specifies that:
945 * the old key exchange algorithm 'diffie-hellman-group1-sha1'
947 should be the main alternative. It will be the main alterna‐
948 tive since it is prepened to the list
949 * The compression algorithm none (= no compression) is removed
951 so compression is enforced
952 For background and more examples see the User's Guide.
954 inet_common_option() = {inet, inet | inet6}
956 IP version to use when the host address is specified as any.
958 auth_methods_common_option() = {auth_methods, string()}
960 Comma-separated string that determines which authentication
962 methods that the client shall support and in which order they
963 are tried. Defaults to "publickey,keyboard-interactive,password"
964 Note that the client is free to use any order and to exclude
966 methods.
967 fd_common_option() = {fd, gen_tcp:socket()}
969 Allows an existing file-descriptor to be used (passed on to the
971 transport protocol).
972 Other data types
974 host() = string() | inet:ip_address() | loopback
975 ip_port() = {inet:ip_address(), inet:port_number()}
977 mod_args() = {Module :: atom(), Args :: list()}
979 mod_fun_args() =
981 {Module :: atom(), Function :: atom(), Args :: list()}
982 open_socket() = gen_tcp:socket()
984 The socket is supposed to be result of a gen_tcp:connect or a
986 gen_tcp:accept. The socket must be in passive mode (that is,
987 opened with the option {active,false}).
988 daemon_ref()
990 Opaque data type representing a daemon.
992 Returned by the functions daemon/1,2,3.
994 connection_ref()
996 Opaque data type representing a connection between a client and
998 a server (daemon).
999 Returned by the functions connect/2,3,4 and ssh_sftp:start_chan‐
1001 nel/2,3.
1002 channel_id()
1004 Opaque data type representing a channel inside a connection.
1006 Returned by the functions ssh_connection:session_channel/2,4.
1008 opaque_client_options
1010 opaque_daemon_options
1012 opaque_common_options
1014 Opaque types that define experimental options that are not to be
1016 used in products.
1017
1019 close(ConnectionRef) -> ok | {error, term()}
1020 Types:
1022 ConnectionRef = connection_ref()
1024 Closes an SSH connection.
1026 connect(Host, Port, Options) -> Result
1028 connect(Host, Port, Options, NegotiationTimeout) -> Result
1029 connect(TcpSocket, Options) -> Result
1030 connect(TcpSocket, Options, NegotiationTimeout) -> Result
1031 Types:
1033 Host = host()
1035 Port = inet:port_number()
1036 Options = client_options()
1037 TcpSocket = open_socket()
1038 NegotiationTimeout = timeout()
1039 Result = {ok, connection_ref()} | {error, term()}
1040 Connects to an SSH server at the Host on Port.
1042 As an alternative, an already open TCP socket could be passed to
1044 the function in TcpSocket. The SSH initiation and negotiation
1045 will be initiated on that one with the SSH that should be at the
1046 other end.
1047 No channel is started. This is done by calling ssh_connec‐
1049 tion:session_channel/[2, 4].
1050 The NegotiationTimeout is in milli-seconds. The default value is
1052 infinity. For connection timeout, use the option connect_time‐
1053 out.
1054 connection_info(ConnectionRef, Keys) -> ConnectionInfo
1056 Types:
1058 ConnectionRef = connection_ref()
1060 Keys =
1061 [client_version | server_version | user | peer | sock‐
1062 name]
1063 ConnectionInfo =
1064 [{client_version, Version} |
1065 {server_version, Version} |
1066 {user, string()} |
1067 {peer, {inet:hostname(), ip_port()}} |
1068 {sockname, ip_port()}]
1069 Version = {ProtocolVersion, VersionString :: string()}
1070 ProtocolVersion =
1071 {Major :: integer() >= 1, Minor :: integer() >= 0}
1072 Retrieves information about a connection. The list Keys defines
1074 which information that is returned.
1075 daemon(Port | TcpSocket) -> Result
1077 daemon(Port | TcpSocket, Options) -> Result
1078 daemon(HostAddress, Port, Options) -> Result
1079 Types:
1081 Port = integer()
1083 TcpSocket = open_socket()
1084 Options = daemon_options()
1085 HostAddress = host() | any
1086 Result = {ok, daemon_ref()} | {error, atom()}
1087 Starts a server listening for SSH connections on the given port.
1089 If the Port is 0, a random free port is selected. See dae‐
1090 mon_info/1 about how to find the selected port number.
1091 As an alternative, an already open TCP socket could be passed to
1093 the function in TcpSocket. The SSH initiation and negotiation
1094 will be initiated on that one when an SSH starts at the other
1095 end of the TCP socket.
1096 For a description of the options, see Daemon Options.
1098 Please note that by historical reasons both the HostAddress
1100 argument and the gen_tcp connect_option() {ip,Address} set the
1101 listening address. This is a source of possible inconsistent
1102 settings.
1103 The rules for handling the two address passing options are:
1105 * if HostAddress is an IP-address, that IP-address is the lis‐
1107 tening address. An 'ip'-option will be discarded if present.
1108 * if HostAddress is the atom loopback, the listening address
1110 is loopback and an loopback address will be choosen by the
1111 underlying layers. An 'ip'-option will be discarded if
1112 present.
1113 * if HostAddress is the atom any and no 'ip'-option is
1115 present, the listening address is any and the socket will
1116 listen to all addresses
1117 * if HostAddress is any and an 'ip'-option is present, the
1119 listening address is set to the value of the 'ip'-option
1120 daemon_info(Daemon) -> {ok, DaemonInfo} | {error, term()}
1122 Types:
1124 Daemon = daemon_ref()
1126 DaemonInfo =
1127 [{ip, inet:ip_address()} |
1128 {port, inet:port_number()} |
1129 {profile, term()}]
1130 Returns a key-value list with information about the daemon.
1132 default_algorithms() -> algs_list()
1134 Returns a key-value list, where the keys are the different types
1136 of algorithms and the values are the algorithms themselves.
1137 See the User's Guide for an example.
1139 shell(Host | TcpSocket) -> Result
1141 shell(Host | TcpSocket, Options) -> Result
1142 shell(Host, Port, Options) -> Result
1143 Types:
1145 Host = host()
1147 TcpSocket = open_socket()
1148 Port = inet:port_number()
1149 Options = client_options()
1150 Result = ok | {error, Reason::term()}
1151 Connects to an SSH server at Host and Port (defaults to 22) and
1153 starts an interactive shell on that remote host.
1154 As an alternative, an already open TCP socket could be passed to
1156 the function in TcpSocket. The SSH initiation and negotiation
1157 will be initiated on that one and finaly a shell will be started
1158 on the host at the other end of the TCP socket.
1159 For a description of the options, see Client Options.
1161 The function waits for user input, and does not return until the
1163 remote shell is ended (that is, exit from the shell).
1164 start() -> ok | {error, term()}
1166 start(Type) -> ok | {error, term()}
1168 Types:
1170 Type = permanent | transient | temporary
1172 Utility function that starts the applications crypto, pub‐
1174 lic_key, and ssh. Default type is temporary. For more informa‐
1175 tion, see the application(3) manual page in Kernel.
1176 stop() -> ok | {error, term()}
1178 Stops the ssh application. For more information, see the appli‐
1180 cation(3) manual page in Kernel.
1181 stop_daemon(DaemonRef :: daemon_ref()) -> ok
1183 stop_daemon(Address :: inet:ip_address(),
1185 Port :: inet:port_number()) ->
1186 ok
1187 stop_daemon(Address :: any | inet:ip_address(),
1189 Port :: inet:port_number(),
1190 Profile :: atom()) ->
1191 ok
1192 Stops the listener and all connections started by the listener.
1194 stop_listener(SysSup :: daemon_ref()) -> ok
1196 stop_listener(Address :: inet:ip_address(),
1198 Port :: inet:port_number()) ->
1199 ok
1200 stop_listener(Address :: any | inet:ip_address(),
1202 Port :: inet:port_number(),
1203 Profile :: term()) ->
1204 ok
1205 Stops the listener, but leaves existing connections started by
1207 the listener operational.
1208Ericsson AB ssh 4.7.6 ssh(3)