Merge branch 'for_adding_sshmngr' into 'devel'

sshmngr: Update README as sshmngr UCI is deprecated

See merge request !2

README.md

 # SSH Manager
 
-This package contains code for the Device.SSH. object. The Server objects map to server sections in sshmngr UCI. The AuthorisedKey object maps to file content of backend. Keys can also be added via ubus methods exposed via sshmngr.
+This package contains code for the Device.SSH. object:
 
-## Configuration
+- This package is also responsible for selecting which backend will be compiled.
+- Further information on sshmngr: [docs/arch/SSH.md](./docs/arch/SSH.md) file.
+- Further information on sshd: [docs/guide/sshd_as_backend.md](./docs/guide/sshd_as_backend.md) file.
 
-### UCI
+## Dependencies (backends)
 
-```
-root@iopsys:~# cat /etc/config/sshmngr 
+With the introduction of sshmngr, the default package for ssh is changed from dropbear to **sshd** by OpenSSH (without PAM support). However, this can be customized using the following CONFIG options during compilation:
 
-config server
-	option enable '1'
-	option PasswordAuth '1'
-	option RootPasswordAuth '1'
-	option RootLogin '1'
-	option Port '22'
-	option activationdate '2024-04-02T08:42:46+02:00'
-	option server_instance '1'
-	option server_alias 'cpe-1'
-	option ActivationDate '2024-04-02T09:09:50+02:00'
-	option InstanceId '1'
-	option Alias 'cpe-1'
-	option Interface 'lan'
-
-config server 'server_2'
-	option enable '1'
-	option Port '22'
-	option IdleTimeout '180'
-	option SSHKeepAlive '300'
-	option RootLogin '1'
-	option PasswordAuth '1'
-	option RootPasswordAuth '1'
-	option MaxAuthTries '3'
-	option InstanceId '2'
-	option Alias 'cpe-2'
-	option Interface 'wan'
-	option ActivationDate '2024-04-02T09:13:24+02:00'
-```
-
-### TR-181 data-model
-
-```
-root@iopsys:~# icwmpd -c get Device.SSH.
-Device.SSH.ServerNumberOfEntries => 2
-Device.SSH.AuthorizedKeyNumberOfEntries => 0
-Device.SSH.Status => Enabled
-Device.SSH.Server.1.Enable => 1
-Device.SSH.Server.1.Alias => cpe-1
-Device.SSH.Server.1.Interface => Device.IP.Interface.1
-Device.SSH.Server.1.Port => 22
-Device.SSH.Server.1.IdleTimeout => 0
-Device.SSH.Server.1.KeepAlive => 300
-Device.SSH.Server.1.AllowRootLogin => 1
-Device.SSH.Server.1.AllowPasswordLogin => 1
-Device.SSH.Server.1.AllowRootPasswordLogin => 1
-Device.SSH.Server.1.MaxAuthTries => 3
-Device.SSH.Server.1.ActivationDate => 2024-04-02T09:09:50+02:00
-Device.SSH.Server.1.PID => 13987
-Device.SSH.Server.1.SessionNumberOfEntries => 0
-Device.SSH.Server.2.Enable => 1
-Device.SSH.Server.2.Alias => cpe-2
-Device.SSH.Server.2.Interface => Device.IP.Interface.2
-Device.SSH.Server.2.Port => 22
-Device.SSH.Server.2.IdleTimeout => 180
-Device.SSH.Server.2.KeepAlive => 300
-Device.SSH.Server.2.AllowRootLogin => 1
-Device.SSH.Server.2.AllowPasswordLogin => 1
-Device.SSH.Server.2.AllowRootPasswordLogin => 1
-Device.SSH.Server.2.MaxAuthTries => 3
-Device.SSH.Server.2.ActivationDate => 2024-04-02T09:13:24+02:00
-Device.SSH.Server.2.PID => 17425
-Device.SSH.Server.2.SessionNumberOfEntries => 1
-Device.SSH.Server.2.Session.1.IPAddress => 192.168.20.6
-Device.SSH.Server.2.Session.1.Port => 54950
-```
-
-### Ubus methods
-
-```
-root@iopsys:~# ubus -v list sshmngr
-'sshmngr' @0ec7131a
-	"dump":{"server_name":"String"}
-	"kill_session":{"session_pid":"String","server_name":"String"}
-	"list_keys":{}
-	"add_pubkey":{"current_key":"String","new_key":"String"}
-	"remove_pubkey":{"key":"String"}
-```
-
-- *kill_session*: we can kill individual session or all sessions of a server.
-- *add_pubkey*: if current_key is present, then replace, otherwise add a public key.
+- CONFIG_SSHMNGR_BACKEND_OPENSSH (this is default)
+- CONFIG_SSHMNGR_BACKEND_OPENSSH_PAM
+- CONFIG_SSHMNGR_BACKEND_DROPBEAR

docs/.pages

+title: "SSHMNGR"
+
+nav:
+    - "arch"
+    - "api"
+    - "spec"
+    - "guide"
+    - "..."

docs/api/.pages

+title: "SSHMNGR"
+
+nav:
+    - "ubus"
+    - "uci"
+    - "..."

docs/api/ubus/.pages

+title: "SSHMNGR"
+
+nav:
+    - "..."

docs/api/uci/.pages

+title: "SSHMNGR"
+
+nav:
+    - "..."

docs/arch/.pages

+title: "SSHMNGR"
+hide: true

docs/arch/SSH.md

+# TR-181 SSH data-model
+
+Aim of this document is to explain how the Device.SSH.Server and Device.SSH.AuthorizedKeys datamodel objects are mapped in backend.
+
+As per the definition in TR-181:
+
+- Device.SSH.Server allows setting up SSH servers.
+- Device.SSH.AuthorizedKey allows adding client public keys to use key based authentication.
+
+## UCI Configuration
+
+- The UCI for sshd and dropbear is similar except for some options.
+
+### Options availability
+
+| Option           | dropbear | sshd     |
+| :---             | :----:   | :---:    |
+| SSHKeepAlive     | Present  | Absent   |
+| RecvWindowSize   | Present  | Absent   |
+| rsakeyfile       | Present  | Absent   |
+| keyfile          | Present  | Absent   |
+| verbose          | Present  | Absent   |
+| AllowUsers       | Absent   | Present  |
+| MacAlgorithms    | Absent   | Present  |
+
+
+- For dropbear options, please visit dropbear UCI help web page.
+- For sshd options, please visit: [docs/guide/sshd.md](./docs/guide/sshd.md) file.
+
+### Default config
+
+```
+config sshd
+	option enable '1'
+	option Port '22'
+	option RootLogin '1'
+	option PasswordAuth '1'
+	option RootPasswordAuth '1'
+	list AllowUsers 'root'
+	list MacAlgorithms 'hmac-sha1'
+	list MacAlgorithms 'hmac-sha2-256'
+	list MacAlgorithms 'hmac-sha2-512'
+```
+
+## TR-181 data-model example
+
+The following UCI and TR-181 data model configuration is equivalent:
+
+### sshd UCI
+
+```
+config sshd 'server_1'
+	option enable '1'
+	option Port '22'
+	option IdleTimeout '180'
+	option RootLogin '1'
+	option PasswordAuth '1'
+	option RootPasswordAuth '1'
+	option MaxAuthTries '3'
+	option Interface 'wan'
+```
+
+### TR-181 data-model
+
+```
+root@iopsys:~# icwmpd -c get Device.SSH.
+Device.SSH.ServerNumberOfEntries => 1
+Device.SSH.AuthorizedKeyNumberOfEntries => 0
+Device.SSH.Server.1.Enable => 1
+Device.SSH.Server.1.Alias => cpe-1
+Device.SSH.Server.1.Interface => Device.IP.Interface.2
+Device.SSH.Server.1.Port => 22
+Device.SSH.Server.1.IdleTimeout => 180
+Device.SSH.Server.1.KeepAlive => 300
+Device.SSH.Server.1.AllowRootLogin => 1
+Device.SSH.Server.1.AllowPasswordLogin => 1
+Device.SSH.Server.1.AllowRootPasswordLogin => 1
+Device.SSH.Server.1.MaxAuthTries => 3
+Device.SSH.Server.1.ActivationDate => 2024-04-02T09:13:24+02:00
+Device.SSH.Server.1.PID => 17425
+Device.SSH.Server.1.SessionNumberOfEntries => 1
+Device.SSH.Server.1.Session.1.IPAddress => 192.168.20.6
+Device.SSH.Server.1.Session.1.Port => 54950
+Device.SSH.AuthorizedKey.1.Alias => cpe-1
+Device.SSH.AuthorizedKey.1.Key => <some-client-public-key>
+```
+
+### Operate command
+
+Data model provides us with an operate command to kill a specific session of a specific server. For example:
+
+```
+obuspa -c operate "Device.SSH.Server.1.Session.1.Delete()"
+```
+
+### Ubus methods
+
+```
+root@iopsys:~# ubus -v list sshmngr
+'sshmngr' @0ec7131a
+	"dump":{"server_name":"String"}
+	"kill_session":{"session_pid":"String","server_name":"String"}
+	"list_keys":{}
+	"add_pubkey":{"current_key":"String","new_key":"String"}
+	"remove_pubkey":{"key":"String"}
+```
+
+- *dump*: dump information about servers and sessions.
+- *kill_session*: we can kill individual session or all sessions of a server.
+- *list_keys*: list authorized keys.
+- *add_pubkey*: if current_key is present, then replace, otherwise add a public key (authorized key).
+- *remove_pubkey*: remove public key of a client (authorized key).

docs/guide/.pages

+title: "SSHMNGR"
+
+nav:
+    - "..."

docs/guide/sshd_as_backend.md

+# SSHD as backend
+
+The ssh daemon provided by OpenSSH is called sshd. This document provides an outline of its behaviour,
+to aid understand the behaviour and configuration when using sshd as backend for sshmngr.
+
+## Configuration
+
+- The UCI file for sshd is called "sshd".
+- Each section of the UCI file represents an ssh server.
+- The section can be of the type "sshd".
+- The datamodel maps one-to-one to the sshd uci file.
+
+### Options
+
+- The default here applies if the option is not used.
+
+| Name             | Type     | Default     | Description |
+| :---             | :----:   | :---:       | :---        |
+| AllowUsers       | string   | empty       | username allowed to log in, no value means all users |
+| BannerFile       | string   | empty       | the path to the file containing the banner used in ssh |
+| enable           | bool     | true        | whether this server is enabled or not |
+| GatewayPorts     | bool     | false       | whether remote hosts are allowed to connect to forwarded ports |
+| Interface        | string   | empty       | interface whose address to bind to, no value means all interfaces |
+| MacAlgorithms    | string   | empty       | the available MAC (message authentication code) algorithm, no value means all |
+| MaxAuthTries     | number   | 6           | number of authentication attempts allowed |
+| PasswordAuth     | bool     | true        | whether to allow password based authentication |
+| Port             | number   | 22          | port to listen on |
+| PublishOverMdns  | bool     | true        | whether to announce an ssh service over mdns |
+| RootLogin        | bool     | true        | whether to allow authentication for root |
+| RootPasswordAuth | bool     | true        | whether to allow password based authentication for root |
+
+- There is a iowrt default config with which the device comes up, which is different and as follows:
+```
+config sshd
+        option enable '1'
+        option Port '22'
+        option RootLogin '1'
+        option PasswordAuth '1'
+        option RootPasswordAuth '1'
+        list AllowUsers 'root'
+        list MacAlgorithms 'hmac-sha1'
+        list MacAlgorithms 'hmac-sha2-256'
+        list MacAlgorithms 'hmac-sha2-512'
+```
+- Please note that the options AllowUsers and MacAlgorithms are not configurable via TR181 and hence must be properly set in the customer default UCI config or represented by vendor extensions.
+
+### AuthorizedKeys
+
+- Client authorized keys allow to authenticate a client without a password.
+- Client authorized keys can be generated at the client using the ssh-keygen utility. For more details on this, please refer to *ssh-keygen manpage*.
+- Client authorized keys can be added/removed via sshmngr ubus functions or by directly modifying following file (for sshd):
+
+```
+/root/.ssh/authorized_keys
+```
+or by executing the following at the client side
+```
+ssh-copy-id username@remote_host
+```
+
+## Notes
+
+### MaxAuthTries behaviour (Too many authentication failures)
+
+This is one of the most frequent complain we recieve when using openssh, please find some guidelines to understanding the actual cause of the problem and how to fix it.
+
+- When we try to ssh onto a server from the client side, then the client makes authentication attempts to the server, most commonly using public-keys or passwords.
+- When an ssh attempt is made by the client without specifying *option PreferredAuthentications*, the client first tries to authenticate by sending its public-keys.
+- It is only when the public-key based authentication fails that the client falls back to password based authentication.
+- Please note that there could be more than one public-keys available at the client and while usually the client sends one public-key, it depends on the ssh-client config as to how many public-keys will it try authenticating with before falling back to password.
+- On the sshd server, *option MaxAuthTries* configures the number of authentication attempts that are allowed over an ssh connection attempt, its default value is 6.
+- Therefore, if a client tries 6 or more keys and none of them work, then error will be displayed without even asking for a password, even if the *option MaxAuthTries* is set to 6.
+- This could also lead you to believe that the value set for *option MaxAuthTries* by you, is not taking effect since the attempts to authenticate with the public-keys are usually invisible to the eye (unless you are using ssh -v).
+- To avoid this problem you could force the sshd **clients** (common for Linux users) to only password based authentication as follows:
+
+```
+ssh -o PreferredAuthentications=password <user>@<device-ip>
+```
+- You could also delete obstelete keys to avoid unnecessary authentication attempts.
+
+### Fixed number of password prompts by sshd client
+
+Another problem that we commonly come across is that even when the value for *option MaxAuthTries* at the sshd server is set to a value greater than 3, the sshd client still prompts only for 3 passwords attempts before giving up and closing the ssh connection. Please find some guidelines to understanding the cause of this and to work around this problem as follows:
+
+- The number of password prompts is not just controlled by the *option MaxAuthTries* on the sshd server, but also the *option NumberOfPasswordPrompts* on the sshd client.
+- By default, sshd **clients** (common for Linux users) only allow 3 password attempts since the default value of *option NumberOfPasswordPrompts* is 3.
+- This can be changed by setting option **NumberOfPasswordPrompts** in **ssh_config** on the client side
+```
+Add the following line to /etc/ssh/ssh_config on the client:
+
+NumberOfPasswordPrompts 6
+```
+or by passing it as a command line option like,
+```
+ssh -o PreferredAuthentications=password -o NumberOfPasswordPrompts=6 <user>@<device-ip>
+```
+
+It is strongly advised to not use a value of *option NumberOfPasswordPrompts* at the client side which is less than the value of *option MaxAuthTries* at the server side.
+
+
+- In general, if something goes wrong with your attempt to ssh onto the device, its always good to check what is exactly going wrong by doing a more verbose ssh attempt with the option *-v*
+
+```
+ssh -v <user>@<device-ip>
+```

docs/spec/.pages

+title: "SSHMNGR"
+hide: true