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
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_specs()}
283 subsystem_specs() = [subsystem_spec()]
285 subsystem_spec() = {Name :: string(), mod_args()}
287 Defines a subsystem in the daemon.
289 The subsystem_name is the name that a client requests to start
291 with for example ssh_connection:subsystem/4.
292 The channel_callback is the module that implements the
294 ssh_server_channel (replaces ssh_daemon_channel) behaviour in
295 the daemon. See the section Creating a Subsystem in the User's
296 Guide for more information and an example.
297 If the subsystems option is not present, the value of
299 ssh_sftpd:subsystem_spec([]) is used. This enables the sftp sub‐
300 system by default. The option can be set to the empty list if
301 you do not want the daemon to run any subsystems.
302 shell_daemon_option() = {shell, shell_spec()}
304 shell_spec() = mod_fun_args() | shell_fun() | disabled
306 shell_fun() = 'shell_fun/1'() | 'shell_fun/2'()
308 'shell_fun/1'() = fun((User :: string()) -> pid())
310 'shell_fun/2'() =
312 fun((User :: string(), PeerAddr :: inet:ip_address()) -> pid())
313 Defines the read-eval-print loop used in a daemon when a shell
315 is requested by the client. The default is to use the Erlang
316 shell: {shell, start, []}
317 See the option exec-option for a description of how the daemon
319 executes shell-requests and exec-requests depending on the
320 shell- and exec-options.
321 exec_daemon_option() = {exec, exec_spec()}
323 exec_spec() =
325 {direct, exec_fun()} | disabled | deprecated_exec_opt()
326 exec_fun() = 'exec_fun/1'() | 'exec_fun/2'() | 'exec_fun/3'()
328 'exec_fun/1'() = fun((Cmd :: string()) -> exec_result())
330 'exec_fun/2'() =
332 fun((Cmd :: string(), User :: string()) -> exec_result())
333 'exec_fun/3'() =
335 fun((Cmd :: string(),
336 User :: string(),
337 ClientAddr :: ip_port()) ->
338 exec_result())
339 exec_result() =
341 {ok, Result :: term()} | {error, Reason :: term()}
342 This option changes how the daemon executes exec-requests from
344 clients. The term in the return value is formatted to a string
345 if it is a non-string type. No trailing newline is added in the
346 ok-case.
347 See the User's Guide section on One-Time Execution for examples.
349 Error texts are returned on channel-type 1 which usually is
351 piped to stderr on e.g Linux systems. Texts from a successful
352 execution are returned on channel-type 0 and will in similar
353 manner be piped to stdout. The exit-status code is set to 0 for
354 success and 255 for errors. The exact results presented on the
355 client side depends on the client and the client's operating
356 system.
357 In case of the {direct, exec_fun()} variant or no exec-option at
359 all, all reads from standard_input will be from the received
360 data-events of type 0. Those are sent by the client. Similarily
361 all writes to standard_output will be sent as data-events to the
362 client. An OS shell client like the command 'ssh' will usally
363 use stdin and stdout for the user interface.
364 The option cooperates with the daemon-option shell in the fol‐
366 lowing way:
367 1. If neither the exec-option nor the shell-option is
369 present::
370 The default Erlang evaluator is used both for exec and shell
371 requests. The result is returned to the client.
372 2. If the exec_spec's value is disabled (the shell-option may
374 or may not be present)::
375 No exec-requests are executed but shell-requests are not
376 affected, they follow the shell_spec's value.
377 3. If the exec-option is present and the exec_spec value =/=
379 disabled (the shell-option may or may not be present)::
380 The exec_spec fun() is called with the same number of param‐
381 eters as the arity of the fun, and the result is returned to
382 the client. Shell-requests are not affected, they follow the
383 shell_spec's value.
384 4. If the exec-option is absent, and the shell-option is
386 present with the default Erlang shell as the shell_spec's
387 value::
388 The default Erlang evaluator is used both for exec and shell
389 requests. The result is returned to the client.
390 5. If the exec-option is absent, and the shell-option is
392 present with a value that is neither the default Erlang shell
393 nor the value disabled::
394 The exec-request is not evaluated and an error message is
395 returned to the client. Shell-requests are executed accord‐
396 ing to the value of the shell_spec.
397 6. If the exec-option is absent, and the shell_spec's value is
399 disabled::
400 Exec requests are executed by the default shell, but shell-
401 requests are not executed.
402 If a custom CLI is installed (see the option ssh_cli) the rules
404 above are replaced by thoose implied by the custom CLI.
405 Note:
407 The exec-option has existed for a long time but has not previ‐
408 ously been documented. The old definition and behaviour are
409 retained but obey the rules 1-6 above if conflicting. The old
410 and undocumented style should not be used in new programs.
411 deprecated_exec_opt() = function() | mod_fun_args()
414 Old-style exec specification that are kept for compatibility,
416 but should not be used in new programs
417 ssh_cli_daemon_option() = {ssh_cli, mod_args() | no_cli}
419 Provides your own CLI implementation in a daemon.
421 It is a channel callback module that implements a shell and com‐
423 mand execution. The shell's read-eval-print loop can be custom‐
424 ized, using the option shell. This means less work than imple‐
425 menting an own CLI channel. If ssh_cli is set to no_cli, the CLI
426 channels like shell and exec are disabled and only subsystem
427 channels are allowed.
428 authentication_daemon_options() =
430 ssh_file:system_dir_daemon_option() |
431 {auth_method_kb_interactive_data, prompt_texts()} |
432 {user_passwords, [{UserName :: string(), Pwd :: string()}]} |
433 {password, string()} |
434 {pwdfun, pwdfun_2() | pwdfun_4()}
435 prompt_texts() = kb_int_tuple() | kb_int_fun_3()
437 kb_int_tuple() =
439 {Name :: string(),
440 Instruction :: string(),
441 Prompt :: string(),
442 Echo :: boolean()}
443 kb_int_fun_3() =
445 fun((Peer :: ip_port(), User :: string(), Service :: string()) ->
446 kb_int_tuple())
447 pwdfun_2() =
449 fun((User :: string(), Password :: string()) -> boolean())
450 pwdfun_4() =
452 fun((User :: string(),
453 Password :: string(),
454 PeerAddress :: ip_port(),
455 State :: any()) ->
456 boolean() |
457 disconnect |
458 {boolean(), NewState :: any()})
459 auth_method_kb_interactive_data:
461 Sets the text strings that the daemon sends to the client
462 for presentation to the user when using keyboard-interactive
463 authentication.
464 If the fun/3 is used, it is called when the actual authenti‐
466 cation occurs and may therefore return dynamic data like
467 time, remote ip etc.
468 The parameter Echo guides the client about need to hide the
470 password.
471 The default value is: {auth_method_kb_interactive_data,
473 {"SSH server", "Enter password for \""++User++"\"", "pass‐
474 word: ", false}>
475 user_passwords:
477 Provides passwords for password authentication. The pass‐
478 words are used when someone tries to connect to the server
479 and public key user-authentication fails. The option pro‐
480 vides a list of valid usernames and the corresponding pass‐
481 words.
482 password:
484 Provides a global password that authenticates any user.
485 Warning:
487 Intended to facilitate testing.
488 From a security perspective this option makes the server very
490 vulnerable.
491 pwdfun with pwdfun_4():
494 Provides a function for password validation. This could used
495 for calling an external system or handeling passwords stored
496 as hash values.
497 This fun can also be used to make delays in authentication
499 tries for example by calling timer:sleep/1.
500 To facilitate for instance counting of failed tries, the
502 State variable could be used. This state is per connection
503 only. The first time the pwdfun is called for a connection,
504 the State variable has the value undefined.
505 The fun should return:
507 * true if the user and password is valid
509 * false if the user or password is invalid
511 * disconnect if a SSH_MSG_DISCONNECT message should be sent
513 immediately. It will be followed by a close of the under‐
514 lying tcp connection.
515 * {true, NewState:any()} if the user and password is valid
517 * {false, NewState:any()} if the user or password is invalid
519 A third usage is to block login attempts from a missbehaving
521 peer. The State described above can be used for this. The
522 return value disconnect is useful for this.
523 pwdfun with pwdfun_2():
525 Provides a function for password validation. This function
526 is called with user and password as strings, and returns:
527 * true if the user and password is valid
529 * false if the user or password is invalid
531 This variant is kept for compatibility.
533 diffie_hellman_group_exchange_daemon_option() =
535 {dh_gex_groups,
536 [explicit_group()] |
537 explicit_group_file() |
538 ssh_moduli_file()} |
539 {dh_gex_limits, {Min :: integer() >= 1, Max :: integer() >= 1}}
540 explicit_group() =
542 {Size :: integer() >= 1,
543 G :: integer() >= 1,
544 P :: integer() >= 1}
545 explicit_group_file() = {file, string()}
547 ssh_moduli_file() = {ssh_moduli_file, string()}
549 dh_gex_groups:
551 Defines the groups the server may choose among when diffie-
552 hellman-group-exchange is negotiated. See RFC 4419 for
553 details. The three variants of this option are:
554 {Size=integer(),G=integer(),P=integer()}:
556 The groups are given explicitly in this list. There may be
557 several elements with the same Size. In such a case, the
558 server will choose one randomly in the negotiated Size.
559 {file,filename()}:
561 The file must have one or more three-tuples {Size=inte‐
562 ger(),G=integer(),P=integer()} terminated by a dot. The
563 file is read when the daemon starts.
564 {ssh_moduli_file,filename()}:
566 The file must be in ssh-keygen moduli file format. The
567 file is read when the daemon starts.
568 The default list is fetched from the public_key application.
570 dh_gex_limits:
572 Limits what a client can ask for in diffie-hellman-group-
573 exchange. The limits will be {MaxUsed = min(MaxClient,Max),
574 MinUsed = max(MinClient,Min)} where MaxClient and MinClient
575 are the values proposed by a connecting client.
576 The default value is {0,infinity}.
578 If MaxUsed < MinUsed in a key exchange, it will fail with a
580 disconnect.
581 See RFC 4419 for the function of the Max and Min values.
583 negotiation_timeout_daemon_option() =
585 {negotiation_timeout, timeout()}
586 Maximum time in milliseconds for the authentication negotiation.
588 Defaults to 120000 ms (2 minutes). If the client fails to log in
589 within this time, the connection is closed.
590 hardening_daemon_options() =
592 {max_sessions, integer() >= 1} |
593 {max_channels, integer() >= 1} |
594 {parallel_login, boolean()} |
595 {minimal_remote_max_packet_size, integer() >= 1}
596 max_sessions:
598 The maximum number of simultaneous sessions that are
599 accepted at any time for this daemon. This includes sessions
600 that are being authorized. Thus, if set to N, and N clients
601 have connected but not started the login process, connection
602 attempt N+1 is aborted. If N connections are authenticated
603 and still logged in, no more logins are accepted until one
604 of the existing ones log out.
605 The counter is per listening port. Thus, if two daemons are
607 started, one with {max_sessions,N} and the other with
608 {max_sessions,M}, in total N+M connections are accepted for
609 the whole ssh application.
610 Notice that if parallel_login is false, only one client at a
612 time can be in the authentication phase.
613 By default, this option is not set. This means that the num‐
615 ber is not limited.
616 max_channels:
618 The maximum number of channels with active remote subsystem
619 that are accepted for each connection to this daemon
620 By default, this option is not set. This means that the num‐
622 ber is not limited.
623 parallel_login:
625 If set to false (the default value), only one login is han‐
626 dled at a time. If set to true, an unlimited number of login
627 attempts are allowed simultaneously.
628 If the max_sessions option is set to N and parallel_login is
630 set to true, the maximum number of simultaneous login
631 attempts at any time is limited to N-K, where K is the num‐
632 ber of authenticated connections present at this daemon.
633 Warning:
635 Do not enable parallel_logins without protecting the server by
636 other means, for example, by the max_sessions option or a
637 firewall configuration. If set to true, there is no protection
638 against DOS attacks.
639 minimal_remote_max_packet_size:
642 The least maximum packet size that the daemon will accept in
643 channel open requests from the client. The default value is
644 0.
645 callbacks_daemon_options() =
647 {failfun,
648 fun((User :: string(),
649 PeerAddress :: inet:ip_address(),
650 Reason :: term()) ->
651 term())} |
652 {connectfun,
653 fun((User :: string(),
654 PeerAddress :: inet:ip_address(),
655 Method :: string()) ->
656 term())}
657 connectfun:
659 Provides a fun to implement your own logging when a user
660 authenticates to the server.
661 failfun:
663 Provides a fun to implement your own logging when a user
664 fails to authenticate.
665 send_ext_info_daemon_option() = {send_ext_info, boolean()}
667 Make the server (daemon) tell the client that the server accepts
669 extension negotiation, that is, include ext-info-s in the kex‐
670 init message sent. See RFC 8308 for details and ssh(6) for a
671 list of currently implemented extensions.
672 Default value is true which is compatible with other implementa‐
674 tions not supporting ext-info.
675 Options common to clients and daemons
677 common_options() = [common_option()]
678 common_option() =
680 ssh_file:user_dir_common_option() |
681 profile_common_option() |
682 max_idle_time_common_option() |
683 key_cb_common_option() |
684 disconnectfun_common_option() |
685 unexpectedfun_common_option() |
686 ssh_msg_debug_fun_common_option() |
687 rekey_limit_common_option() |
688 id_string_common_option() |
689 pref_public_key_algs_common_option() |
690 preferred_algorithms_common_option() |
691 modify_algorithms_common_option() |
692 auth_methods_common_option() |
693 inet_common_option() |
694 fd_common_option()
695 The options above can be used both in clients and in daemons
697 (servers). They are further explained below.
698 profile_common_option() = {profile, atom()}
700 Used together with ip-address and port to uniquely identify a
702 ssh daemon. This can be useful in a virtualized environment,
703 where there can be more that one server that has the same ip-
704 address and port. If this property is not explicitly set, it is
705 assumed that the the ip-address and port uniquely identifies the
706 SSH daemon.
707 max_idle_time_common_option() = {idle_time, timeout()}
709 Sets a time-out on a connection when no channels are open.
711 Defaults to infinity. The unit is milliseconds.
712 The timeout is not active until channels are started, so it does
714 not limit the time from the connection creation to the first
715 channel opening.
716 rekey_limit_common_option() =
718 {rekey_limit,
719 Bytes ::
720 limit_bytes() |
721 {Minutes :: limit_time(), Bytes :: limit_bytes()}}
722 limit_bytes() = integer() >= 0 | infinity
724 limit_time() = integer() >= 1 | infinity
726 Sets the limit when rekeying is to be initiated. Both the max
728 time and max amount of data could be configured:
729 * {Minutes, Bytes} initiate rekeying when any of the limits
731 are reached.
732 * Bytes initiate rekeying when Bytes number of bytes are
734 transferred, or at latest after one hour.
735 When a rekeying is done, both the timer and the byte counter are
737 restarted. Defaults to one hour and one GByte.
738 If Minutes is set to infinity, no rekeying will ever occur due
740 to that max time has passed. Setting Bytes to infinity will
741 inhibit rekeying after a certain amount of data has been trans‐
742 ferred. If the option value is set to {infinity, infinity}, no
743 rekeying will be initiated. Note that rekeying initiated by the
744 peer will still be performed.
745 key_cb_common_option() =
747 {key_cb,
748 Module :: atom() | {Module :: atom(), Opts :: [term()]}}
749 Module implementing the behaviour ssh_client_key_api and/or
751 ssh_server_key_api. Can be used to customize the handling of
752 public keys. If callback options are provided along with the
753 module name, they are made available to the callback module via
754 the options passed to it under the key 'key_cb_private'.
755 The Opts defaults to [] when only the Module is specified.
757 The default value of this option is {ssh_file, []}. See also the
759 manpage of ssh_file.
760 A call to the call-back function F will be
762 Module:F(..., [{key_cb_private,Opts}|UserOptions])
764 where ... are arguments to F as in ssh_client_key_api and/or
767 ssh_server_key_api. The UserOptions are the options given to
768 ssh:connect, ssh:shell or ssh:daemon.
769 pref_public_key_algs_common_option() =
771 {pref_public_key_algs, [pubkey_alg()]}
772 List of user (client) public key algorithms to try to use.
774 The default value is the public_key entry in the list returned
776 by ssh:default_algorithms/0.
777 If there is no public key of a specified type available, the
779 corresponding entry is ignored. Note that the available set is
780 dependent on the underlying cryptolib and current user's public
781 keys.
782 See also the option user_dir for specifying the path to the
784 user's keys.
785 disconnectfun_common_option() =
787 {disconnectfun, fun((Reason :: term()) -> void | any())}
788 Provides a fun to implement your own logging when the peer dis‐
790 connects.
791 unexpectedfun_common_option() =
793 {unexpectedfun,
794 fun((Message :: term(), {Host :: term(), Port :: term()}) ->
795 report | skip)}
796 Provides a fun to implement your own logging or other action
798 when an unexpected message arrives. If the fun returns report
799 the usual info report is issued but if skip is returned no
800 report is generated.
801 ssh_msg_debug_fun_common_option() =
803 {ssh_msg_debug_fun,
804 fun((ssh:connection_ref(),
805 AlwaysDisplay :: boolean(),
806 Msg :: binary(),
807 LanguageTag :: binary()) ->
808 any())}
809 Provide a fun to implement your own logging of the SSH message
811 SSH_MSG_DEBUG. The last three parameters are from the message,
812 see RFC 4253, section 11.3. The connection_ref() is the refer‐
813 ence to the connection on which the message arrived. The return
814 value from the fun is not checked.
815 The default behaviour is ignore the message. To get a printout
817 for each message with AlwaysDisplay = true, use for example
818 {ssh_msg_debug_fun, fun(_,true,M,_)-> io:format("DEBUG: ~p~n",
819 [M]) end}
820 id_string_common_option() =
822 {id_string,
823 string() |
824 random |
825 {random, Nmin :: integer() >= 1, Nmax :: integer() >= 1}}
826 The string the daemon will present to a connecting peer ini‐
828 tially. The default value is "Erlang/VSN" where VSN is the ssh
829 application version number.
830 The value random will cause a random string to be created at
832 each connection attempt. This is to make it a bit more difficult
833 for a malicious peer to find the ssh software brand and version.
834 The value {random, Nmin, Nmax} will make a random string with at
836 least Nmin characters and at most Nmax characters.
837 preferred_algorithms_common_option() =
839 {preferred_algorithms, algs_list()}
840 algs_list() = [alg_entry()]
842 alg_entry() =
844 {kex, [kex_alg()]} |
845 {public_key, [pubkey_alg()]} |
846 {cipher, double_algs(cipher_alg())} |
847 {mac, double_algs(mac_alg())} |
848 {compression, double_algs(compression_alg())}
849 kex_alg() =
851 'diffie-hellman-group-exchange-sha1' |
852 'diffie-hellman-group-exchange-sha256' |
853 'diffie-hellman-group1-sha1' | 'diffie-hellman-group14-sha1' |
854 'diffie-hellman-group14-sha256' |
855 'diffie-hellman-group16-sha512' |
856 'diffie-hellman-group18-sha512' | 'curve25519-sha256' |
857 'curve25519-sha256@libssh.org' | 'curve448-sha512' |
858 'ecdh-sha2-nistp256' | 'ecdh-sha2-nistp384' |
859 'ecdh-sha2-nistp521'
860 pubkey_alg() =
862 'ecdsa-sha2-nistp256' | 'ecdsa-sha2-nistp384' |
863 'ecdsa-sha2-nistp521' | 'ssh-ed25519' | 'ssh-ed448' |
864 'rsa-sha2-256' | 'rsa-sha2-512' | 'ssh-dss' | 'ssh-rsa'
865 cipher_alg() =
867 '3des-cbc' | 'AEAD_AES_128_GCM' | 'AEAD_AES_256_GCM' |
868 'aes128-cbc' | 'aes128-ctr' | 'aes128-gcm@openssh.com' |
869 'aes192-ctr' | 'aes192-cbc' | 'aes256-cbc' | 'aes256-ctr' |
870 'aes256-gcm@openssh.com' | 'chacha20-poly1305@openssh.com'
871 mac_alg() =
873 'AEAD_AES_128_GCM' | 'AEAD_AES_256_GCM' | 'hmac-sha1' |
874 'hmac-sha1-96' | 'hmac-sha2-256' | 'hmac-sha2-512'
875 compression_alg() = none | zlib | 'zlib@openssh.com'
877 double_algs(AlgType) =
879 [{client2server, [AlgType]} | {server2client, [AlgType]}] |
880 [AlgType]
881 List of algorithms to use in the algorithm negotiation. The
883 default algs_list() can be obtained from default_algorithms/0.
884 If an alg_entry() is missing in the algs_list(), the default
886 value is used for that entry.
887 Here is an example of this option:
889 {preferred_algorithms,
891 [{public_key,['ssh-rsa','ssh-dss']},
892 {cipher,[{client2server,['aes128-ctr']},
893 {server2client,['aes128-cbc','3des-cbc']}]},
894 {mac,['hmac-sha2-256','hmac-sha1']},
895 {compression,[none,zlib]}
896 ]
897 }
898 The example specifies different algorithms in the two directions
901 (client2server and server2client), for cipher but specifies the
902 same algorithms for mac and compression in both directions. The
903 kex (key exchange) is implicit but public_key is set explicitly.
904 For background and more examples see the User's Guide.
906 If an algorithm name occurs more than once in a list, the behav‐
908 iour is undefined. The tags in the property lists are also
909 assumed to occur at most one time.
910 Warning:
912 Changing the values can make a connection less secure. Do not
913 change unless you know exactly what you are doing. If you do not
914 understand the values then you are not supposed to change them.
915 modify_algorithms_common_option() =
918 {modify_algorithms, modify_algs_list()}
919 modify_algs_list() =
921 [{append, algs_list()} |
922 {prepend, algs_list()} |
923 {rm, algs_list()}]
924 Modifies the list of algorithms to use in the algorithm negotia‐
926 tion. The modifications are applied after the option pre‐
927 ferred_algorithms (if existing) is applied.
928 The algoritm for modifications works like this:
930 * Input is the modify_algs_list() and a set of algorithms A
932 obtained from the preferred_algorithms option if existing,
933 or else from the ssh:default_algorithms/0.
934 * The head of the modify_algs_list() modifies A giving the
936 result A'.
937 The possible modifications are:
939 * Append or prepend supported but not enabled algorithm(s)
941 to the list of algorithms. If the wanted algorithms
942 already are in A they will first be removed and then
943 appended or prepended,
944 * Remove (rm) one or more algorithms from A.
946 * Repeat the modification step with the tail of mod‐
948 ify_algs_list() and the resulting A'.
949 If an unsupported algorithm is in the modify_algs_list(), it
951 will be silently ignored
952 If there are more than one modify_algorithms options, the result
954 is undefined.
955 Here is an example of this option:
957 {modify_algorithms,
959 [{prepend, [{kex, ['diffie-hellman-group1-sha1']}],
960 {rm, [{compression, [none]}]}
961 ]
962 }
963 The example specifies that:
966 * the old key exchange algorithm 'diffie-hellman-group1-sha1'
968 should be the main alternative. It will be the main alterna‐
969 tive since it is prepened to the list
970 * The compression algorithm none (= no compression) is removed
972 so compression is enforced
973 For background and more examples see the User's Guide.
975 inet_common_option() = {inet, inet | inet6}
977 IP version to use when the host address is specified as any.
979 auth_methods_common_option() = {auth_methods, string()}
981 Comma-separated string that determines which authentication
983 methods that the client shall support and in which order they
984 are tried. Defaults to "publickey,keyboard-interactive,password"
985 Note that the client is free to use any order and to exclude
987 methods.
988 fd_common_option() = {fd, gen_tcp:socket()}
990 Allows an existing file-descriptor to be used (passed on to the
992 transport protocol).
993 Other data types
995 host() = string() | inet:ip_address() | loopback
996 ip_port() = {inet:ip_address(), inet:port_number()}
998 mod_args() = {Module :: atom(), Args :: list()}
1000 mod_fun_args() =
1002 {Module :: atom(), Function :: atom(), Args :: list()}
1003 open_socket() = gen_tcp:socket()
1005 The socket is supposed to be result of a gen_tcp:connect or a
1007 gen_tcp:accept. The socket must be in passive mode (that is,
1008 opened with the option {active,false}).
1009 daemon_ref()
1011 Opaque data type representing a daemon.
1013 Returned by the functions daemon/1,2,3.
1015 connection_ref()
1017 Opaque data type representing a connection between a client and
1019 a server (daemon).
1020 Returned by the functions connect/2,3,4 and ssh_sftp:start_chan‐
1022 nel/2,3.
1023 channel_id()
1025 Opaque data type representing a channel inside a connection.
1027 Returned by the functions ssh_connection:session_channel/2,4.
1029 connection_info_tuple() =
1031 {client_version, version()} |
1032 {server_version, version()} |
1033 {user, string()} |
1034 {peer, {inet:hostname(), ip_port()}} |
1035 {sockname, ip_port()} |
1036 {options, client_options()} |
1037 {algorithms, conn_info_algs()} |
1038 {channels, conn_info_channels()}
1039 version() = {protocol_version(), software_version()}
1041 protocol_version() =
1043 {Major :: integer() >= 1, Minor :: integer() >= 0}
1044 software_version() = string()
1046 conn_info_algs() =
1048 [{kex, kex_alg()} |
1049 {hkey, pubkey_alg()} |
1050 {encrypt, cipher_alg()} |
1051 {decrypt, cipher_alg()} |
1052 {send_mac, mac_alg()} |
1053 {recv_mac, mac_alg()} |
1054 {compress, compression_alg()} |
1055 {decompress, compression_alg()} |
1056 {send_ext_info, boolean()} |
1057 {recv_ext_info, boolean()}]
1058 conn_info_channels() = [proplists:proplist()]
1060 Return values from the connection_info/1 and connection_info/2
1062 functions.
1063 In the option info tuple are only the options included that dif‐
1065 fers from the default values.
1066 daemon_info_tuple() =
1068 {port, inet:port_number()} |
1069 {ip, inet:ip_address()} |
1070 {profile, atom()} |
1071 {options, daemon_options()}
1072 Return values from the daemon_info/1 and daemon_info/2 func‐
1074 tions.
1075 In the option info tuple are only the options included that dif‐
1077 fers from the default values.
1078 opaque_client_options
1080 opaque_daemon_options
1082 opaque_common_options
1084 Opaque types that define experimental options that are not to be
1086 used in products.
1087
1089 close(ConnectionRef) -> ok | {error, term()}
1090 Types:
1092 ConnectionRef = connection_ref()
1094 Closes an SSH connection.
1096 connect(Host, Port, Options) -> Result
1098 connect(Host, Port, Options, NegotiationTimeout) -> Result
1099 connect(TcpSocket, Options) -> Result
1100 connect(TcpSocket, Options, NegotiationTimeout) -> Result
1101 Types:
1103 Host = host()
1105 Port = inet:port_number()
1106 Options = client_options()
1107 TcpSocket = open_socket()
1108 NegotiationTimeout = timeout()
1109 Result = {ok, connection_ref()} | {error, term()}
1110 Connects to an SSH server at the Host on Port.
1112 As an alternative, an already open TCP socket could be passed to
1114 the function in TcpSocket. The SSH initiation and negotiation
1115 will be initiated on that one with the SSH that should be at the
1116 other end.
1117 No channel is started. This is done by calling ssh_connec‐
1119 tion:session_channel/[2, 4].
1120 The NegotiationTimeout is in milli-seconds. The default value is
1122 infinity. For connection timeout, use the option connect_time‐
1123 out.
1124 connection_info(ConnectionRef) -> InfoTupleList
1126 connection_info(ConnectionRef, Key :: ItemList | Item) ->
1128 InfoTupleList | InfoTuple
1129 Types:
1131 ConnectionRef = connection_ref()
1133 ItemList = [Item]
1134 Item =
1135 client_version | server_version | user | peer | sockname
1136 |
1137 options | algorithms | sockname
1138 InfoTupleList = [InfoTuple]
1139 InfoTuple = connection_info_tuple()
1140 Returns information about a connection intended for e.g debug‐
1142 ging or logging.
1143 When the Key is a single Item, the result is a single InfoTuple
1145 set_sock_opts(ConnectionRef, SocketOptions) ->
1147 ok | {error, inet:posix()}
1148 Types:
1150 ConnectionRef = connection_ref()
1152 SocketOptions = [gen_tcp:option()]
1153 Sets tcp socket options on the tcp-socket below an ssh connec‐
1155 tion.
1156 This function calls the inet:setopts/2, read that documentation
1158 and for gen_tcp:option(). All gen_tcp socket options except
1159 active, deliver, mode and packet are allowed. The excluded
1160 options are reserved by the SSH application.
1161 Warning:
1163 This is an extremly dangerous function. You use it on your own
1164 risk.
1165 Some options are OS and OS version dependent. Do not use it
1167 unless you know what effect your option values will have on an
1168 TCP stream.
1169 Some values may destroy the functionality of the SSH protocol.
1171 get_sock_opts(ConnectionRef, SocketGetOptions) ->
1174 ok | {error, inet:posix()}
1175 Types:
1177 ConnectionRef = connection_ref()
1179 SocketGetOptions = [gen_tcp:option_name()]
1180 Get tcp socket option values of the tcp-socket below an ssh con‐
1182 nection.
1183 This function calls the inet:getopts/2, read that documentation.
1185 daemon(Port | TcpSocket) -> Result
1187 daemon(Port | TcpSocket, Options) -> Result
1188 daemon(HostAddress, Port, Options) -> Result
1189 Types:
1191 Port = integer()
1193 TcpSocket = open_socket()
1194 Options = daemon_options()
1195 HostAddress = host() | any
1196 Result = {ok, daemon_ref()} | {error, atom()}
1197 Starts a server listening for SSH connections on the given port.
1199 If the Port is 0, a random free port is selected. See dae‐
1200 mon_info/1 about how to find the selected port number.
1201 As an alternative, an already open TCP socket could be passed to
1203 the function in TcpSocket. The SSH initiation and negotiation
1204 will be initiated on that one when an SSH starts at the other
1205 end of the TCP socket.
1206 For a description of the options, see Daemon Options.
1208 Please note that by historical reasons both the HostAddress
1210 argument and the gen_tcp connect_option() {ip,Address} set the
1211 listening address. This is a source of possible inconsistent
1212 settings.
1213 The rules for handling the two address passing options are:
1215 * if HostAddress is an IP-address, that IP-address is the lis‐
1217 tening address. An 'ip'-option will be discarded if present.
1218 * if HostAddress is the atom loopback, the listening address
1220 is loopback and an loopback address will be choosen by the
1221 underlying layers. An 'ip'-option will be discarded if
1222 present.
1223 * if HostAddress is the atom any and no 'ip'-option is
1225 present, the listening address is any and the socket will
1226 listen to all addresses
1227 * if HostAddress is any and an 'ip'-option is present, the
1229 listening address is set to the value of the 'ip'-option
1230 daemon_info(DaemonRef) ->
1232 {ok, InfoTupleList} | {error, bad_daemon_ref}
1233 daemon_info(DaemonRef, Key :: ItemList | Item) ->
1235 InfoTupleList | InfoTuple | {error, bad_daemon_ref}
1236 Types:
1238 DaemonRef = daemon_ref()
1240 ItemList = [Item]
1241 Item = ip | port | profile | options
1242 InfoTupleList = [InfoTuple]
1243 InfoTuple = daemon_info_tuple()
1244 Returns information about a daemon intended for e.g debugging or
1246 logging.
1247 When the Key is a single Item, the result is a single InfoTuple
1249 Note that daemon_info/1 and daemon_info/2 returns different
1251 types due to compatibility reasons.
1252 default_algorithms() -> algs_list()
1254 Returns a key-value list, where the keys are the different types
1256 of algorithms and the values are the algorithms themselves.
1257 See the User's Guide for an example.
1259 shell(Host | TcpSocket) -> Result
1261 shell(Host | TcpSocket, Options) -> Result
1262 shell(Host, Port, Options) -> Result
1263 Types:
1265 Host = host()
1267 TcpSocket = open_socket()
1268 Port = inet:port_number()
1269 Options = client_options()
1270 Result = ok | {error, Reason::term()}
1271 Connects to an SSH server at Host and Port (defaults to 22) and
1273 starts an interactive shell on that remote host.
1274 As an alternative, an already open TCP socket could be passed to
1276 the function in TcpSocket. The SSH initiation and negotiation
1277 will be initiated on that one and finaly a shell will be started
1278 on the host at the other end of the TCP socket.
1279 For a description of the options, see Client Options.
1281 The function waits for user input, and does not return until the
1283 remote shell is ended (that is, exit from the shell).
1284 start() -> ok | {error, term()}
1286 start(Type) -> ok | {error, term()}
1288 Types:
1290 Type = permanent | transient | temporary
1292 Utility function that starts the applications crypto, pub‐
1294 lic_key, and ssh. Default type is temporary. For more informa‐
1295 tion, see the application(3) manual page in Kernel.
1296 stop() -> ok | {error, term()}
1298 Stops the ssh application. For more information, see the appli‐
1300 cation(3) manual page in Kernel.
1301 stop_daemon(DaemonRef :: daemon_ref()) -> ok
1303 stop_daemon(Address :: inet:ip_address(),
1305 Port :: inet:port_number()) ->
1306 ok
1307 stop_daemon(Address :: any | inet:ip_address(),
1309 Port :: inet:port_number(),
1310 Profile :: atom()) ->
1311 ok
1312 Stops the listener and all connections started by the listener.
1314 stop_listener(SysSup :: daemon_ref()) -> ok
1316 stop_listener(Address :: inet:ip_address(),
1318 Port :: inet:port_number()) ->
1319 ok
1320 stop_listener(Address :: any | inet:ip_address(),
1322 Port :: inet:port_number(),
1323 Profile :: term()) ->
1324 ok
1325 Stops the listener, but leaves existing connections started by
1327 the listener operational.
1328Ericsson AB ssh 4.9 ssh(3)