1ssh(3) Erlang Module Definition ssh(3)
2
6 ssh - Main API of the ssh application
7
9 Interface module for the ssh application.
10 See ssh(6) for details of supported version, algorithms and unicode
12 support.
13
15 The exact behaviour of some functions can be adjusted with the use of
16 options which are documented together with the functions. Generally
17 could each option be used at most one time in each function call. If
18 given two or more times, the effect is not predictable unless explic‐
19 itly documented.
20 The options are of different kinds:
22 Limits:
24 which alters limits in the system, for example number of simultane‐
25 ous login attempts.
26 Timeouts:
28 which give some defined behaviour if too long time elapses before a
29 given event or action, for example time to wait for an answer.
30 Callbacks:
32 which gives the caller of the function the possibility to execute
33 own code on some events, for example calling an own logging func‐
34 tion or to perform an own login function
35 Behaviour:
37 which changes the systems behaviour.
38
40 Type definitions that are used more than once in this module, or
41 abstractions to indicate the intended use of the data type, or both:
42 boolean() =:
44 true | false
45 string() =:
47 [byte()]
48 ssh_daemon_ref() =:
50 opaque() - as returned by ssh:daemon/[1,2,3]
51 ssh_connection_ref() =:
53 opaque() - as returned by ssh:connect/3
54 ip_address() =:
56 inet::ip_address
57 subsystem_spec() =:
59 {subsystem_name(), {channel_callback(), channel_init_args()}}
60 subsystem_name() =:
62 string()
63 channel_callback() =:
65 atom() - Name of the Erlang module implementing the subsystem using
66 the ssh_channel behavior, see ssh_channel(3)
67 key_cb() =:
69 atom() | {atom(), list()}
70 atom() - Name of the erlang module implementing the behaviours
72 ssh_client_key_api or ssh_client_key_api as the case maybe.
73 list() - List of options that can be passed to the callback module.
75 channel_init_args() =:
77 list()
78 algs_list() =:
80 list( alg_entry() )
81 alg_entry() =:
83 {kex, simple_algs()} | {public_key, simple_algs()} | {cipher, dou‐
84 ble_algs()} | {mac, double_algs()} | {compression, double_algs()}
85 simple_algs() =:
87 list( atom() )
88 double_algs() =:
90 [{client2serverlist,simple_algs()},{server2client,simple_algs()}] |
91 simple_algs()
92 modify_algs_list() =:
94 list( {append,algs_list()} | {prepend,algs_list()} |
95 {rm,algs_list()} )
96
98 close(ConnectionRef) -> ok
99 Types:
101 ConnectionRef = ssh_connection_ref()
103 Closes an SSH connection.
105 connect(Host, Port, Options) ->
107 connect(Host, Port, Options, Timeout) ->
108 connect(TcpSocket, Options) ->
109 connect(TcpSocket, Options, Timeout) -> {ok, ssh_connection_ref()} |
110 {error, Reason}
111 Types:
113 Host = string()
115 Port = integer()
116 22 is default, the assigned well-known port number for SSH.
117 Options = [{Option, Value}]
118 Timeout = infinity | integer()
119 Negotiation time-out in milli-seconds. The default value is
120 infinity. For connection time-out, use option {con‐
121 nect_timeout, timeout()}.
122 TcpSocket = port()
123 The socket is supposed to be from gen_tcp:connect or
124 gen_tcp:accept with option {active,false}
125 Connects to an SSH server. No channel is started. This is done
127 by calling ssh_connection:session_channel/[2, 4].
128 Options:
130 {inet, inet | inet6}:
132 IP version to use.
133 {user_dir, string()}:
135 Sets the user directory, that is, the directory containing
136 ssh configuration files for the user, such as known_hosts,
137 id_rsa, id_dsa, and authorized_key. Defaults to the direc‐
138 tory normally referred to as ~/.ssh.
139 {dsa_pass_phrase, string()}:
141 If the user DSA key is protected by a passphrase, it can be
142 supplied with this option.
143 {rsa_pass_phrase, string()}:
145 If the user RSA key is protected by a passphrase, it can be
146 supplied with this option.
147 {ecdsa_pass_phrase, string()}:
149 If the user ECDSA key is protected by a passphrase, it can
150 be supplied with this option.
151 {silently_accept_hosts, boolean()}
153 {silently_accept_hosts, CallbackFun}
154 {silently_accept_hosts, {HashAlgoSpec, CallbackFun} }
155 HashAlgoSpec = crypto:digest_type() | [ crypto:digest_type()
157 ]
158 CallbackFun = fun(PeerName, FingerPrint) -> boolean()
159 PeerName = string()
160 FingerPrint = string() | [ string() ] : This option guides
161 the connect function how to act when the connected server
162 presents a Host Key that the client has not seen before. The
163 default is to ask the user with a question on stdio of
164 whether to accept or reject the new Host Key. See also the
165 option user_dir for the path to the file known_hosts where
166 previously accepted Host Keys are recorded.
167 The option can be given in three different forms as seen
169 above:
170 * The value is a boolean(). The value true will make the
172 client accept any unknown Host Key without any user inter‐
173 action. The value false keeps the default behaviour of
174 asking the the user on stdio.
175 * A CallbackFun will be called and the boolean return value
177 true will make the client accept the Host Key. A return
178 value of false will make the client to reject the Host Key
179 and therefore also the connection will be closed. The
180 arguments to the fun are:
181 * PeerName - a string with the name or address of the
183 remote host.
184 * FingerPrint - the fingerprint of the Host Key as pub‐
186 lic_key:ssh_hostkey_fingerprint/1 calculates it.
187 * A tuple {HashAlgoSpec, CallbackFun}. The HashAlgoSpec
189 specifies which hash algorithm shall be used to calculate
190 the fingerprint used in the call of the CallbackFun. The
191 HashALgoSpec is either an atom or a list of atoms as the
192 first argument in public_key:ssh_hostkey_fingerprint/2. If
193 it is a list of hash algorithm names, the FingerPrint
194 argument in the CallbackFun will be a list of fingerprints
195 in the same order as the corresponding name in the HashAl‐
196 goSpec list.
197 {save_accepted_host, boolean()}:
199 If true, the client saves an accepted host key to avoid the
200 accept question the next time the same host is connected. If
201 the option key_cb is not present, the key is saved in the
202 file "known_hosts".
203 If false, the key is not saved and the key will still be
205 unknown at the next access of the same host.
206 {user_interaction, boolean()}:
208 If false, disables the client to connect to the server if
209 any user interaction is needed, such as accepting the server
210 to be added to the known_hosts file, or supplying a pass‐
211 word. Defaults to true. Even if user interaction is allowed
212 it can be suppressed by other options, such as
213 silently_accept_hosts and password. However, those options
214 are not always desirable to use from a security point of
215 view.
216 {disconnectfun, fun(Reason:term()) -> _}:
218 Provides a fun to implement your own logging when a server
219 disconnects the client.
220 {unexpectedfun, fun(Message:term(), Peer) -> report | skip }:
222 Provides a fun to implement your own logging or other action
223 when an unexpected message arrives. If the fun returns
224 report the usual info report is issued but if skip is
225 returned no report is generated.
226 Peer is in the format of {Host,Port}.
228 {pref_public_key_algs, list()}:
230 List of user (client) public key algorithms to try to use.
231 The default value is the public_key entry in
233 ssh:default_algorithms/0.
234 If there is no public key of a specified type available, the
236 corresponding entry is ignored. Note that the available set
237 is dependent on the underlying cryptolib and current user's
238 public keys.
239 {preferred_algorithms, algs_list()}:
241 List of algorithms to use in the algorithm negotiation. The
242 default algs_list() can be obtained from default_algo‐
243 rithms/0.
244 If an alg_entry() is missing in the algs_list(), the default
246 value is used for that entry.
247 Here is an example of this option:
249 {preferred_algorithms,
251 [{public_key,['ssh-rsa','ssh-dss']},
252 {cipher,[{client2server,['aes128-ctr']},
253 {server2client,['aes128-cbc','3des-cbc']}]},
254 {mac,['hmac-sha2-256','hmac-sha1']},
255 {compression,[none,zlib]}
256 ]
257 }
258 The example specifies different algorithms in the two direc‐
261 tions (client2server and server2client), for cipher but
262 specifies the same algorithms for mac and compression in
263 both directions. The kex (key exchange) is implicit but pub‐
264 lic_key is set explicitly.
265 For background and more examples see the User's Guide.
267 Warning:
269 Changing the values can make a connection less secure. Do not
270 change unless you know exactly what you are doing. If you do
271 not understand the values then you are not supposed to change
272 them.
273 {modify_algorithms, modify_algs_list()}:
276 Modifies the list of algorithms to use in the algorithm
277 negotiation. The modifications are applied after the option
278 preferred_algorithms (if existing) is applied.
279 The algoritm for modifications works like this:
281 * Input is the modify_algs_list() and a set of algorithms A
283 obtained from the preferred_algorithms option if existing,
284 or else from the ssh:default_algorithms/0.
285 * The head of the modify_algs_list() modifies A giving the
287 result A'.
288 The possible modifications are:
290 * Append or prepend supported but not enabled algorithm(s)
292 to the list of algorithms. If the wanted algorithms
293 already are in A they will first be removed and then
294 appended or prepended,
295 * Remove (rm) one or more algorithms from A.
297 * Repeat the modification step with the tail of mod‐
299 ify_algs_list() and the resulting A'.
300 If an unsupported algorithm is in the modify_algs_list(), it
302 will be silently ignored
303 If there are more than one modify_algorithms options, the
305 result is undefined.
306 Here is an example of this option:
308 {modify_algorithms,
310 [{prepend, [{kex, ['diffie-hellman-group1-sha1']}],
311 {rm, [{compression, [none]}]}
312 ]
313 }
314 The example specifies that:
317 * the old key exchange algorithm 'diffie-hellman-
319 group1-sha1' should be the main alternative. It will be
320 the main alternative since it is prepened to the list
321 * The compression algorithm none (= no compression) is
323 removed so compression is enforced
324 For background and more examples see the User's Guide.
326 {dh_gex_limits,{Min=integer(),I=integer(),Max=integer()}}:
328 Sets the three diffie-hellman-group-exchange parameters that
329 guides the connected server in choosing a group. See RFC
330 4419 for the function of thoose. The default value is {1024,
331 6144, 8192}.
332 {connect_timeout, timeout()}:
334 Sets a time-out on the transport layer connection. For
335 gen_tcp the time is in milli-seconds and the default value
336 is infinity.
337 {auth_methods, string()}:
339 Comma-separated string that determines which authentication
340 methods that the client shall support and in which order
341 they are tried. Defaults to "publickey,keyboard-interac‐
342 tive,password"
343 {user, string()}:
345 Provides a username. If this option is not given, ssh reads
346 from the environment (LOGNAME or USER on UNIX, USERNAME on
347 Windows).
348 {password, string()}:
350 Provides a password for password authentication. If this
351 option is not given, the user is asked for a password, if
352 the password authentication method is attempted.
353 {recv_ext_info, boolean()}:
355 Tell the server that the client accepts extension negotia‐
356 tion. See Draft-ietf-curdle-ssh-ext-info (work in progress)
357 for details.
358 Currently implemented extension is server-sig-algs which is
360 the list of the server's preferred user's public key algo‐
361 rithms.
362 Default value is true.
364 {key_cb, key_cb()}:
366 Module implementing the behaviour ssh_client_key_api. Can be
367 used to customize the handling of public keys. If callback
368 options are provided along with the module name, they are
369 made available to the callback module via the options passed
370 to it under the key 'key_cb_private'.
371 {quiet_mode, atom() = boolean()}:
373 If true, the client does not print anything on authoriza‐
374 tion.
375 {id_string, random | string()}:
377 The string that the client presents to a connected server
378 initially. The default value is "Erlang/VSN" where VSN is
379 the ssh application version number.
380 The value random will cause a random string to be created at
382 each connection attempt. This is to make it a bit more dif‐
383 ficult for a malicious peer to find the ssh software brand
384 and version.
385 {fd, file_descriptor()}:
387 Allows an existing file descriptor to be used (by passing it
388 on to the transport protocol).
389 {rekey_limit, integer()}:
391 Provides, in bytes, when rekeying is to be initiated.
392 Defaults to once per each GB and once per hour.
393 {idle_time, integer()}:
395 Sets a time-out on a connection when no channels are active.
396 Defaults to infinity.
397 {ssh_msg_debug_fun, fun(ConnectionRef::ssh_connection_ref(),
399 AlwaysDisplay::boolean(), Msg::binary(), Language‐
400 Tag::binary()) -> _}:
401 Provide a fun to implement your own logging of the SSH mes‐
402 sage SSH_MSG_DEBUG. The last three parameters are from the
403 message, see RFC4253, section 11.3. The ConnectionRef is the
404 reference to the connection on which the message arrived.
405 The return value from the fun is not checked.
406 The default behaviour is ignore the message. To get a print‐
408 out for each message with AlwaysDisplay = true, use for
409 example {ssh_msg_debug_fun, fun(_,true,M,_)-> io:for‐
410 mat("DEBUG: ~p~n", [M]) end}
411 connection_info(ConnectionRef, [Option]) ->[{Option, Value}]
413 Types:
415 Option = client_version | server_version | user | peer |
417 sockname
418 Value = [option_value()]
419 option_value() = {{Major::integer(), Minor::integer()}, Ver‐
420 sionString::string()} | User::string() | Peer::{inet:host‐
421 name(), {inet::ip_adress(), inet::port_number()}} | Sock‐
422 name::{inet::ip_adress(), inet::port_number()}
423 Retrieves information about a connection.
425 daemon(Port) ->
427 daemon(Port, Options) ->
428 daemon(HostAddress, Port, Options) ->
429 daemon(TcpSocket) ->
430 daemon(TcpSocket, Options) -> {ok, ssh_daemon_ref()} | {error, atom()}
431 Types:
433 Port = integer()
435 HostAddress = ip_address() | any | loopback
436 Options = [{Option, Value}]
437 Option = atom()
438 Value = term()
439 TcpSocket = port()
440 The socket is supposed to be from gen_tcp:connect or
441 gen_tcp:accept with option {active,false}
442 Starts a server listening for SSH connections on the given port.
444 If the Port is 0, a random free port is selected. See dae‐
445 mon_info/1 about how to find the selected port number.
446 Please note that by historical reasons both the HostAddress
448 argument and the inet socket option ip set the listening
449 address. This is a source of possible inconsistent settings.
450 The rules for handling the two address passing options are:
452 * if HostAddress is an IP-address, that IP-address is the lis‐
454 tening address. An 'ip'-option will be discarded if present.
455 * if HostAddress is loopback, the listening address is loop‐
457 back and an loopback address will be choosen by the underly‐
458 ing layers. An 'ip'-option will be discarded if present.
459 * if HostAddress is any and no 'ip'-option is present, the
461 listening address is any and the socket will listen to all
462 addresses
463 * if HostAddress is any and an 'ip'-option is present, the
465 listening address is set to the value of the 'ip'-option
466 Options:
468 {inet, inet | inet6}:
470 IP version to use when the host address is specified as any.
471 {subsystems, [subsystem_spec()]}:
473 Provides specifications for handling of subsystems. The
474 "sftp" subsystem specification is retrieved by calling
475 ssh_sftpd:subsystem_spec/1. If the subsystems option is not
476 present, the value of [ssh_sftpd:subsystem_spec([])] is
477 used. The option can be set to the empty list if you do not
478 want the daemon to run any subsystems.
479 {shell, {Module, Function, Args} | fun(string() = User) - >
481 pid() | fun(string() = User, ip_address() = PeerAddr) ->
482 pid()}:
483 Defines the read-eval-print loop used when a shell is
484 requested by the client. The default is to use the Erlang
485 shell: {shell, start, []}
486 {ssh_cli, {channel_callback(), channel_init_args()} | no_cli}:
488 Provides your own CLI implementation, that is, a channel
489 callback module that implements a shell and command execu‐
490 tion. The shell read-eval-print loop can be customized,
491 using the option shell. This means less work than implement‐
492 ing an own CLI channel. If set to no_cli, the CLI channels
493 are disabled and only subsystem channels are allowed.
494 {user_dir, string()}:
496 Sets the user directory. That is, the directory containing
497 ssh configuration files for the user, such as known_hosts,
498 id_rsa, id_dsa, and authorized_key. Defaults to the direc‐
499 tory normally referred to as ~/.ssh.
500 {system_dir, string()}:
502 Sets the system directory, containing the host key files
503 that identify the host keys for ssh. Defaults to /etc/ssh.
504 For security reasons, this directory is normally accessible
505 only to the root user.
506 {auth_methods, string()}:
508 Comma-separated string that determines which authentication
509 methods that the server is to support and in what order they
510 are tried. Defaults to "publickey,keyboard-interactive,pass‐
511 word"
512 Note that the client is free to use any order and to exclude
514 methods.
515 {auth_method_kb_interactive_data, PromptTexts}
517 where:
518 PromptTexts = kb_int_tuple() |
519 fun(Peer::{IP::tuple(),Port::integer()}, User::string(),
520 Service::string()) -> kb_int_tuple()
521 kb_int_tuple() = {Name::string(), Instruction::string(),
522 Prompt::string(), Echo::boolean()}: Sets the text strings
523 that the daemon sends to the client for presentation to the
524 user when using keyboar-interactive authentication. If the
525 fun/3 is used, it is called when the actual authentication
526 occurs and may therefore return dynamic data like time,
527 remote ip etc.
528 The parameter Echo guides the client about need to hide the
530 password.
531 The default value is: {auth_method_kb_interactive_data,
533 {"SSH server", "Enter password for \""++User++"\"", "pass‐
534 word: ", false}>
535 {user_passwords, [{string() = User, string() = Password}]}:
537 Provides passwords for password authentication. The pass‐
538 words are used when someone tries to connect to the server
539 and public key user-authentication fails. The option pro‐
540 vides a list of valid usernames and the corresponding pass‐
541 words.
542 {password, string()}:
544 Provides a global password that authenticates any user. From
545 a security perspective this option makes the server very
546 vulnerable.
547 {preferred_algorithms, algs_list()}:
549 List of algorithms to use in the algorithm negotiation. The
550 default algs_list() can be obtained from default_algo‐
551 rithms/0.
552 If an alg_entry() is missing in the algs_list(), the default
554 value is used for that entry.
555 Here is an example of this option:
557 {preferred_algorithms,
559 [{public_key,['ssh-rsa','ssh-dss']},
560 {cipher,[{client2server,['aes128-ctr']},
561 {server2client,['aes128-cbc','3des-cbc']}]},
562 {mac,['hmac-sha2-256','hmac-sha1']},
563 {compression,[none,zlib]}
564 ]
565 }
566 The example specifies different algorithms in the two direc‐
569 tions (client2server and server2client), for cipher but
570 specifies the same algorithms for mac and compression in
571 both directions. The kex (key exchange) is implicit but pub‐
572 lic_key is set explicitly.
573 For background and more examples see the User's Guide.
575 Warning:
577 Changing the values can make a connection less secure. Do not
578 change unless you know exactly what you are doing. If you do
579 not understand the values then you are not supposed to change
580 them.
581 {modify_algorithms, modify_algs_list()}:
584 Modifies the list of algorithms to use in the algorithm
585 negotiation. The modifications are applied after the option
586 preferred_algorithms is applied (if existing)
587 The possible modifications are to:
589 * Append or prepend supported but not enabled algorithm(s)
591 to the list of algorithms.
592 If the wanted algorithms already are in the list of algo‐
594 rithms, they will first be removed and then appended or
595 prepended.
596 * Remove (rm) one or more algorithms from the list of algo‐
598 rithms.
599 If an unsupported algorithm is in the list, it will be
601 silently ignored
602 Here is an example of this option:
604 {modify_algorithms,
606 [{prepend, [{kex, ['diffie-hellman-group1-sha1']}],
607 {rm, [{compression, [none]}]}
608 ]
609 }
610 The example specifies that:
613 * the old key exchange algorithm 'diffie-hellman-
615 group1-sha1' should be the main alternative. It will be
616 the main alternative since it is prepened to the list
617 * The compression algorithm none (= no compression) is
619 removed so compression is enforced
620 For background and more examples see the User's Guide.
622 {dh_gex_groups, [{Size=integer(),G=integer(),P=integer()}] |
624 {file,filename()} {ssh_moduli_file,filename()} }:
625 Defines the groups the server may choose among when diffie-
626 hellman-group-exchange is negotiated. See RFC 4419 for
627 details. The three variants of this option are:
628 {Size=integer(),G=integer(),P=integer()}:
630 The groups are given explicitly in this list. There may be
631 several elements with the same Size. In such a case, the
632 server will choose one randomly in the negotiated Size.
633 {file,filename()}:
635 The file must have one or more three-tuples {Size=inte‐
636 ger(),G=integer(),P=integer()} terminated by a dot. The
637 file is read when the daemon starts.
638 {ssh_moduli_file,filename()}:
640 The file must be in ssh-keygen moduli file format. The
641 file is read when the daemon starts.
642 The default list is fetched from the public_key application.
644 {dh_gex_limits,{Min=integer(),Max=integer()}}:
646 Limits what a client can ask for in diffie-hellman-group-
647 exchange. The limits will be {MaxUsed = min(MaxClient,Max),
648 MinUsed = max(MinClient,Min)} where MaxClient and MinClient
649 are the values proposed by a connecting client.
650 The default value is {0,infinity}.
652 If MaxUsed < MinUsed in a key exchange, it will fail with a
654 disconnect.
655 See RFC 4419 for the function of the Max and Min values.
657 {pwdfun, fun(User::string(), Password::string(), PeerAd‐
659 dress::{ip_adress(),port_number()}, State::any()) -> boolean()
660 | disconnect | {boolean(),any()} }:
661 Provides a function for password validation. This could used
662 for calling an external system or if passwords should be
663 stored as a hash. The fun returns:
664 * true if the user and password is valid and
666 * false otherwise.
668 This fun can also be used to make delays in authentication
670 tries for example by calling timer:sleep/1. To facilitate
671 counting of failed tries the State variable could be used.
672 This state is per connection only. The first time the pwdfun
673 is called for a connection, the State variable has the value
674 undefined. The pwdfun can return - in addition to the values
675 above - a new state as:
676 * {true, NewState:any()} if the user and password is valid
678 or
679 * {false, NewState:any()} if the user or password is invalid
681 A third usage is to block login attempts from a missbehaving
683 peer. The State described above can be used for this. In
684 addition to the responses above, the following return value
685 is introduced:
686 * disconnect if the connection should be closed immediately
688 after sending a SSH_MSG_DISCONNECT message.
689 {pwdfun, fun(User::string(), Password::string()) -> bool‐
691 ean()}:
692 Provides a function for password validation. This function
693 is called with user and password as strings, and returns
694 true if the password is valid and false otherwise.
695 This option ({pwdfun,fun/2}) is the same as a subset of the
697 previous ({pwdfun,fun/4}). It is kept for compatibility.
698 {negotiation_timeout, integer()}:
700 Maximum time in milliseconds for the authentication negotia‐
701 tion. Defaults to 120000 (2 minutes). If the client fails to
702 log in within this time, the connection is closed.
703 {max_sessions, pos_integer()}:
705 The maximum number of simultaneous sessions that are
706 accepted at any time for this daemon. This includes sessions
707 that are being authorized. Thus, if set to N, and N clients
708 have connected but not started the login process, connection
709 attempt N+1 is aborted. If N connections are authenticated
710 and still logged in, no more logins are accepted until one
711 of the existing ones log out.
712 The counter is per listening port. Thus, if two daemons are
714 started, one with {max_sessions,N} and the other with
715 {max_sessions,M}, in total N+M connections are accepted for
716 the whole ssh application.
717 Notice that if parallel_login is false, only one client at a
719 time can be in the authentication phase.
720 By default, this option is not set. This means that the num‐
722 ber is not limited.
723 {max_channels, pos_integer()}:
725 The maximum number of channels with active remote subsystem
726 that are accepted for each connection to this daemon
727 By default, this option is not set. This means that the num‐
729 ber is not limited.
730 {parallel_login, boolean()}:
732 If set to false (the default value), only one login is han‐
733 dled at a time. If set to true, an unlimited number of login
734 attempts are allowed simultaneously.
735 If the max_sessions option is set to N and parallel_login is
737 set to true, the maximum number of simultaneous login
738 attempts at any time is limited to N-K, where K is the num‐
739 ber of authenticated connections present at this daemon.
740 Warning:
742 Do not enable parallel_logins without protecting the server by
743 other means, for example, by the max_sessions option or a
744 firewall configuration. If set to true, there is no protection
745 against DOS attacks.
746 {minimal_remote_max_packet_size, non_negative_integer()}:
749 The least maximum packet size that the daemon will accept in
750 channel open requests from the client. The default value is
751 0.
752 {id_string, random | string()}:
754 The string the daemon will present to a connecting peer ini‐
755 tially. The default value is "Erlang/VSN" where VSN is the
756 ssh application version number.
757 The value random will cause a random string to be created at
759 each connection attempt. This is to make it a bit more dif‐
760 ficult for a malicious peer to find the ssh software brand
761 and version.
762 {send_ext_info, boolean()}:
764 Send a list of extensions to the client if the client has
765 asked for it. See Draft-ietf-curdle-ssh-ext-info (work in
766 progress) for details.
767 Currently implemented extension is sending server-sig-algs
769 which is the list of the server's preferred user's public
770 key algorithms.
771 Default value is true.
773 {key_cb, key_cb()}:
775 Module implementing the behaviour ssh_server_key_api. Can be
776 used to customize the handling of public keys. If callback
777 options are provided along with the module name, they are
778 made available to the callback module via the options passed
779 to it under the key 'key_cb_private'.
780 {profile, atom()}:
782 Used together with ip-address and port to uniquely identify
783 a ssh daemon. This can be useful in a virtualized environ‐
784 ment, where there can be more that one server that has the
785 same ip-address and port. If this property is not explicitly
786 set, it is assumed that the the ip-address and port uniquely
787 identifies the SSH daemon.
788 {fd, file_descriptor()}:
790 Allows an existing file-descriptor to be used (passed on to
791 the transport protocol).
792 {failfun, fun(User::string(), PeerAddress::ip_address(), Rea‐
794 son::term()) -> _}:
795 Provides a fun to implement your own logging when a user
796 fails to authenticate.
797 {connectfun, fun(User::string(), PeerAddress::ip_address(),
799 Method::string()) ->_}:
800 Provides a fun to implement your own logging when a user
801 authenticates to the server.
802 {disconnectfun, fun(Reason:term()) -> _}:
804 Provides a fun to implement your own logging when a user
805 disconnects from the server.
806 {unexpectedfun, fun(Message:term(), Peer) -> report | skip }:
808 Provides a fun to implement your own logging or other action
809 when an unexpected message arrives. If the fun returns
810 report the usual info report is issued but if skip is
811 returned no report is generated.
812 Peer is in the format of {Host,Port}.
814 {idle_time, integer()}:
816 Sets a time-out on a connection when no channels are active.
817 Defaults to infinity.
818 {ssh_msg_debug_fun, fun(ConnectionRef::ssh_connection_ref(),
820 AlwaysDisplay::boolean(), Msg::binary(), Language‐
821 Tag::binary()) -> _}:
822 Provide a fun to implement your own logging of the SSH mes‐
823 sage SSH_MSG_DEBUG. The last three parameters are from the
824 message, see RFC4253, section 11.3. The ConnectionRef is the
825 reference to the connection on which the message arrived.
826 The return value from the fun is not checked.
827 The default behaviour is ignore the message. To get a print‐
829 out for each message with AlwaysDisplay = true, use for
830 example {ssh_msg_debug_fun, fun(_,true,M,_)-> io:for‐
831 mat("DEBUG: ~p~n", [M]) end}
832 daemon_info(Daemon) -> {ok, [DaemonInfo]} | {error,Error}
834 Types:
836 DaemonInfo = {port,Port::pos_integer()} | {listen_address,
838 any|ip_address()} | {profile,atom()}
839 Port = integer()
840 Error = bad_daemon_ref
841 Returns a key-value list with information about the daemon. For
843 now, only the listening port is returned. This is intended for
844 the case the daemon is started with the port set to 0.
845 default_algorithms() -> algs_list()
847 Returns a key-value list, where the keys are the different types
849 of algorithms and the values are the algorithms themselves. An
850 example:
851 20> ssh:default_algorithms().
853 [{kex,['diffie-hellman-group1-sha1']},
854 {public_key,['ssh-rsa','ssh-dss']},
855 {cipher,[{client2server,['aes128-ctr','aes128-cbc','3des-cbc']},
856 {server2client,['aes128-ctr','aes128-cbc','3des-cbc']}]},
857 {mac,[{client2server,['hmac-sha2-256','hmac-sha1']},
858 {server2client,['hmac-sha2-256','hmac-sha1']}]},
859 {compression,[{client2server,[none,zlib]},
860 {server2client,[none,zlib]}]}]
861 21>
862 shell(Host) ->
865 shell(Host, Option) ->
866 shell(Host, Port, Option) ->
867 shell(TcpSocket) -> _
868 Types:
870 Host = string()
872 Port = integer()
873 Options - see ssh:connect/3
874 TcpSocket = port()
875 The socket is supposed to be from gen_tcp:connect or
876 gen_tcp:accept with option {active,false}
877 Starts an interactive shell over an SSH server on the given
879 Host. The function waits for user input, and does not return
880 until the remote shell is ended (that is, exit from the shell).
881 start() ->
883 start(Type) -> ok | {error, Reason}
884 Types:
886 Type = permanent | transient | temporary
888 Reason = term()
889 Utility function that starts the applications crypto, pub‐
891 lic_key, and ssh. Default type is temporary. For more informa‐
892 tion, see the application(3) manual page in Kernel.
893 stop() -> ok | {error, Reason}
895 Types:
897 Reason = term()
899 Stops the ssh application. For more information, see the appli‐
901 cation(3) manual page in Kernel.
902 stop_daemon(DaemonRef) ->
904 stop_daemon(Address, Port) -> ok
905 Types:
907 DaemonRef = ssh_daemon_ref()
909 Address = ip_address()
910 Port = integer()
911 Stops the listener and all connections started by the listener.
913 stop_listener(DaemonRef) ->
915 stop_listener(Address, Port) -> ok
916 Types:
918 DaemonRef = ssh_daemon_ref()
920 Address = ip_address()
921 Port = integer()
922 Stops the listener, but leaves existing connections started by
924 the listener operational.
925Ericsson AB ssh 4.6.9.4 ssh(3)