diff --git a/doc/console/serial-console-HLD.md b/doc/console/serial-console-HLD.md new file mode 100644 index 0000000000..446a580e88 --- /dev/null +++ b/doc/console/serial-console-HLD.md @@ -0,0 +1,236 @@ +# Serial-console global config HLD +## Table of Content +- [Serial-console config HLD](#serial-console-global-config-hld) +- [Table of Content](#table-of-content) +- [Revision](#revision) +- [1. Introduction](#1-introduction) +- [1.1. Scope](#11-scope) +- [1.2. Definitions/Abbreviations](#12-definitionsabbreviations) +- [1.3. Overview](#13-overview) +- [1.4. Requirements](#14-requirements) +- [2. Architecture Design](#2-architecture-design) + - [2.1. Configuration modules](#21-configuration-modules) +- [3. High-Level Design](#3-high-level-design) + - [Flow diagram](#flow-diagram) + - [3.1 Flow description](#31-flow-description) + - [3.2 serial-console configurations](#32-serial-console-configurations) +- [4. Init flow](#4-init-flow) + - [4.1. Feature Default](#41-feature-default) +- [5. SAI api](#5-sai-api) +- [6. Configuration and management](#6-configuration-and-management) + - [6.1. SERIAL_CONSOLE configDB table](#61-serial_console-configdb-table) + - [6.2. ConfigDB schemas](#62-configdb-schemas) + - [6.3. CLI/YANG model Enhancements](#63-cliyang-model-enhancements) + - [6.4. Config DB Enhancements](#64-config-db-enhancements) + - [6.5. Manifest (if the feature is an Application Extension)](#65-manifest-if-the-feature-is-an-application-extension) +- [7. Warmboot and Fastboot Design Impact](#7-warmboot-and-fastboot-design-impact) +- [8. Restrictions/Limitations](#8-restrictionslimitations) +- [9. Testing Requirements/Design](#9-testing-requirementsdesign) + - [9.1. Unit Test cases](#91-unit-test-cases) + - [9.2. System Test cases](#92-system-test-cases) +- [10. Open/Action items - if any](#10-openaction-items---if-any) +### Revision + +| Rev | Date | Author | Change Description | +| :---: | :------: | :--------: | ------------------ | +| 0.1 | 16/06/23 | Ivan Davydenko | Initial version | + +## 1. Introduction + +### 1.1. Scope + +This hld doc for serial cli global configurations describes the requirements, architecture and general flow details of serial connection config in SONIC OS based switches. + +### 1.2. Definitions/Abbreviations + + serial - connection achieved via serial interface and represented as _tty_ from the linux perspective; + TCP - Transmission Control protocol + +### 1.3. Overview + +We want to allow configuring serial console global settings. This will feature will include two configurations on first phase. + +### 1.4. Requirements + +This feature requires a dedicated table in the configuration DB, enhancements of hostcfg demon and separate service that updates configutaion files. In order to update the serial-console configurations, we need to have write access in /etc/profile.d/, /proc/sys/kernel/sysrq and /etc/sysctl.d/95-sysrq-sysctl.conf. + +## 2. Architecture Design +### 2.1. Configuration modules +![serial_console_config](serial_console_config.png) + +We want to enhance configDB to include table for serial-console global configurations. In addition, serial-config.service will be added to modify configuration files. + +## 3. High-Level Design + +We want to enable serial-console configuration in SONIC. In order to do so will touch few areas in the system: +1. configDB - to include a dedicated table for configurations +2. hostcfg demon - to trigger dedicated service on config apply. +3. OS config files - specific for this stage we are only /etc/profile.d/tmout-env.sh and /etc/sysctl.d/95-sysrq-sysctl.conf and /proc/sys/kernel/sysrq are going to be modifed by the serial-config.sh runned by serial-config.service . + +##### Flow diagram +![serial_console_flow](serial_console_flow.png) +### 3.1 Flow description +When the feature is enabled, by modifying the DB manually, user will set serial-console configurations by modifing CONFIG_DB in SERIAL_CONSOLE table. + +The hostcfgd daemon will be extended to listen to configurations from SERIAL_CONSOLE table and restarts the serial_console.service. Serial console script will read SERIAL_CONSOLE table and update config files accordingly. + +serial-config.service will start `Before=getty-pre.target` and run serial.config.sh to apply configuration before serial console became available. + +### 3.2 Serial-console configurations + +We want to enable configuring the following attributes: +| Policy | Action | Param values | Default | +|--------------------|-----------------------------------------------------------------------|---------------------|--------------| +| inactivity timeout | Inactivity timeout for serial-console session | 0-35000 (minutes) | 15 | +| sysrq capabilities | Enabling or disabling SysRq functionality for serial-consoles | enabled/disabled | disabled | + +j2 examples: +``` +# tmout-env.sh.j2 +{% set serial_pol = (SERIAL_CONSOLE | d({})).get('POLICIES', {}) -%} +{# apply only for serial tty #} +tty | grep -q tty && \ +export TMOUT={{ serial_pol.inactivity_timeout | int * 60 }} +``` +``` +# sysrq-sysctl.conf.j2 +{% set sysrq = 0 %} +{% set serial_policies = (SERIAL_CONSOLE | d({})).get('POLICIES', {}) -%} +{% if serial_policies.sysrq_capabilities == 'enabled' %} +{% set sysrq = 1 %} +{% endif %} +kernel.sysrq={{ sysrq }} +``` +## 4. Init flow + +During init flow we will set default configurations as mentioned in the table abowe. Default values will be added to init_cfg.json.j2 . +### 4.1. Feature Default + +Description of default values in init_cfg.json regarding serial-console config: +``` +inactivity timeout: 15 // in minutes +sysrq capabilities: disabled +``` +## 5. SAI api +NA +## 6. Configuration and management + +### 6.1. SERIAL_CONSOLE configDB table + +``` +SERIAL_CONSOLE:{ + POLICIES:{ + "inactivity_timeout": {{min}} + "sysrq-capabilities": {{enabled|disabled}} + } +} +``` +### 6.2. ConfigDB schemas +``` +; Defines schema for SERIAL_CONSOLE configuration attributes in SERIAL_CONSOLE table: +inactivity_timeout = 5*DIGIT ; autologout timer - max is 35000 minutes +max_syslogins = "enabled/disabled" ; enabling or disabling sysrq capabilities in linux, default is disabled. +``` + +### 6.3. CLI/YANG model Enhancements +```yang +//filename: sonic-serial-console.yang +module sonic-serial-console { + + yang-version 1.1; + + namespace "http://github.com/Azure/sonic-serial-console"; + prefix cli-sessions; + + description "SERIAL_CONSOLE YANG Module for SONiC-based OS"; + + revision 2023-06-07 { + description "First Revision"; + } + + container sonic-serial-console { + + container SERIAL_CONSOLE { + + description "SERIAL_CONSOLE part of config_db.json"; + + container POLICIES { + + leaf inactivity_timeout { + description "serial-console inactivity-timeout timer value in minutes"; + type int32 { + range "0..35000"; + } + default 15; + } + + leaf sysrq_capabilities { + description "managing SysRq capabilities"; + type enumeration { + enum disabled; + enum enabled; + } + default disabled; + } + } + /* end of container POLICIES */ + } + /* end of container SERIAL_CONSOLE */ + } + /* end of top level container */ +} +/* end of module sonic-serial-console */ + +``` +### 6.4. Config DB Enhancements + +The ConfigDB will be extended with next objects: + +```json +{ + "SERIAL_CONSOLE": { + POLICIES: { + "inactivity_timeout": "15", + "sysrq_capabilities": "disabled", + } + } +} +``` + +### 6.5. Manifest (if the feature is an Application Extension) + +NA + + +## 7. Warmboot and Fastboot Design Impact +NA + +## 8. Restrictions/Limitations + +## 9. Testing Requirements/Design +Explain what kind of unit testing, system testing, regression testing, warmboot/fastboot testing, etc., +Ensure that the existing warmboot/fastboot requirements are met. For example, if the current warmboot feature expects maximum of 1 second or zero second data disruption, the same should be met even after the new feature/enhancement is implemented. Explain the same here. +Example sub-sections for unit test cases and system test cases are given below. + +### 9.1. Unit Test cases +Configuration +1. Configure auto-logout for serial-console. +1.1. Configure and apply non-default auto-logout value (1-2 min.) +1.2. Connect and login via serial-console. Validate auto-logout happend in configured time (1-2 min.) +2. Init flow for auto-logout. +2.1. Don't save previous auto-logout configuration and reboot the switch. +2.2. After boot connect and login via serial-console. Validate that auto-logout didn't happend in previously configured time (1-2 min.) +3. Configure sysrq parameter. +3.1. Configure and apply non-default sysrq-capabilities parameter (enabled) +3.2. Check sysrq parameter value in linux proc filesystem being changed to new applied value of "1" +4. Init flow for sysrq parameter. +4.1. Don`t save previous sysrq configuration and reboot the switch. +4.2. Check sysrq parameter value in linux proc filesystem being equal to default value of "0". + + +### 9.2. System Test cases + +## 10. Open/Action items - if any + + +NOTE: All the sections and sub-sections given above are mandatory in the design document. Users can add additional sections/sub-sections if required. diff --git a/doc/console/serial_console_config.png b/doc/console/serial_console_config.png new file mode 100644 index 0000000000..9b255c0c26 Binary files /dev/null and b/doc/console/serial_console_config.png differ diff --git a/doc/console/serial_console_flow.png b/doc/console/serial_console_flow.png new file mode 100644 index 0000000000..b2939f3a3c Binary files /dev/null and b/doc/console/serial_console_flow.png differ diff --git a/doc/ssh_config/ssh_config.md b/doc/ssh_config/ssh_config.md index 9880e3b46f..49ac6f8294 100644 --- a/doc/ssh_config/ssh_config.md +++ b/doc/ssh_config/ssh_config.md @@ -28,32 +28,38 @@ - [1.13.1. Unit Test cases](#1131-unit-test-cases) - [1.13.2. System Test cases](#1132-system-test-cases) - [1.14. Open/Action items - if any](#114-openaction-items---if-any) -### 1.1. Revision +### 1.1. Revision -### 1.2. Scope +| Rev | Date | Author | Change Description | +| :---: | :------: | :--------: | ------------------ | +| 0.1 | 17/05/23 | Yona Coen | Initial version | +| 0.2 | 16/06/23 | Ivan Davydenko | Add descriptions for auto-logout and max-sessions parameters | + + +### 1.2. Scope This hld doc for ssh server global configurations describes the requirements, architecture and general flow details of ssh server config in SONIC OS based switches. -### 1.3. Definitions/Abbreviations +### 1.3. Definitions/Abbreviations SSH - secure shell TCP - Transmission Control protocol -### 1.4. Overview +### 1.4. Overview We want to allow configuring ssh server global settings. This will feature will include 3 configurations in the first phase, but can be extended easily to include additional configurations. -### 1.5. Requirements +### 1.5. Requirements This feature requires a dedicated table in the configuration DB, and enhancements of hostcfg demon, in order to allow modifing the relvant ssh configuration files. In order to override ssh configurations, we need to have write access to ssh config files such as /etc/ssh/sshd_config -### 1.6. Architecture Design -#### 1.6.1. Configuration modules +### 1.6. Architecture Design +#### 1.6.1. Configuration modules ![ssh_config_flow](ssh_config_flow.png) We want to enhance configDB to include table for ssh server global configurations. In addition, hostcfg demon will include a dedicated flow in order to modify ssh config files, once ssh server global config table entries are changed. -### 1.7. High-Level Design +### 1.7. High-Level Design We want to enable global ssh server configuration in SONIC. In order to do so will touch few areas in the system: 1. configDB - to include a dedicated table for configurations @@ -66,13 +72,19 @@ Note: The Daemon is running in the host (without container) that matches this feature, because it is basically writing policies on ssh config files from the OS. ##### Flow diagram ![ssh_flow_community](ssh_flow_community.png) -#### 1.7.1 Flow description +#### 1.7.1 Flow description When the feature is enabled, by modifying the DB manually, user will set ssh server policies/configuration (see options below) by modifing CONFIG_DB in SSH_SERVER_TABLE. -The hostcfgd daemon will be extended to listen to ssh policies/configurations from SSH_SERVER table, parse the inputs and set the new policies to ssh config files, and update ssh server afterwards. - +The hostcfgd daemon will be extended to listen to ssh policies/configurations from SSH_SERVER table, parse the inputs and set the new policies to ssh config files, and update ssh server afterwards. Inactivity timeout configured by already existing flows in hostcfgd. +Updated .j2 config file for max sessions cofiguration: +``` +# limits.conf.j2 +{% if max_sessions -%} +* - maxsyslogins {{ max_sessions }} +{% endif -%} +``` -#### 1.7.2 ssh server policies +#### 1.7.2 ssh server policies We want to enable configuring the following policies, with default values are taken from OS (Debian): | Policy | Action | Param values | Default OS value | @@ -80,24 +92,28 @@ We want to enable configuring the following policies, with default values are ta | authentication retries | Number of attempts to try to log in before rejecting the session | 3-100 | 6 | | login timeout | SSH session timeout | 1-600 (secs) | 120 | | ports | Port numbers for SSH | 1-65535 | 22 | +| inactivity timeout | Inactivity timeout for SSH session | 0-35000 (min) | 15 | +| max sessions | Max number of concurrent logins | 0-100 | 0 | -### 1.8. Init flow +### 1.8. Init flow During init flow we will set default ssh policies, same as default values in DebianOS. Default values will be added to init_cfg.json.j2, and updated in sshd_config file accordingly. -#### 1.8.1. Feature Default +#### 1.8.1. Feature Default Description of default values in init_cfg.json regarding ssh server config: ``` authentication retries: 6 login timeout: 120 //seconds ports: 22 +inactivity timeout: 15 //minutes +max sessions: 0 // means no limit, as in existing systems ``` -### 1.9. SAI api +### 1.9. SAI api NA -### 1.10. Configuration and management +### 1.10. Configuration and management -#### 1.10.1. SSH_SERVER configDB table +#### 1.10.1. SSH_SERVER configDB table ``` SSH_SERVER:{ @@ -105,6 +121,8 @@ SSH_SERVER:{ "authentication_retries": {{num}} "login_timeout": {{secs}} "ports": {{num}} + "inactivity_timeout": {{min}} + "max_syslogins": {{num}} } } ``` @@ -116,9 +134,11 @@ key = "POLICIES" ;ssh server confi authentication_retries = 3*DIGIT ; number of login attepmts, should be 100 max LOGIN_TIMEOUT = 3*DIGIT ; login timeout in secs unit, max is 600 secs PORTS = 5*DIGIT ; ssh port number - max is 65535 +inactivity_timeout = 5*DIGIT ; inactivity timeout - max is 35000 minutes, 0 means no timeout +max_syslogins = 3*DIGIT ; maximum number of concurrent sessions - max is 100, 0 means no limit ``` -#### 1.10.3. CLI/YANG model Enhancements +#### 1.10.3. CLI/YANG model Enhancements ```yang //filename: sonic-ssh_server.yang module sonic-ssh-server { @@ -161,12 +181,26 @@ module sonic-ssh-server { } } } + leaf inactivity_timeout { + description "inactivity timeout (in minutes), 0 means no timeout"; + default 15; + type uint32 { + range 0..35000; + } + } + leaf max_syslogins { + description "limit of concurrent system logins, 0 means no limit"; + default 0; + type uint32 { + range 0..100; + } + } }/*container POLICIES */ } /* container SSH_SERVER */ }/* container sonic-ssh-server */ }/* end of module sonic-ssh-server */ ``` -#### 1.10.4. Config DB Enhancements +#### 1.10.4. Config DB Enhancements The ConfigDB will be extended with next objects: @@ -177,38 +211,42 @@ The ConfigDB will be extended with next objects: "authentication_retries": "6", "login_timeout": "120", "ports": "22", + "inactivity_timeout": "15", + "max_syslogins": "0" } } } ``` -#### 1.10.5. Manifest (if the feature is an Application Extension) +#### 1.10.5. Manifest (if the feature is an Application Extension) NA -### 1.11. Warmboot and Fastboot Design Impact +### 1.11. Warmboot and Fastboot Design Impact NA -### 1.12. Restrictions/Limitations +### 1.12. Restrictions/Limitations -### 1.13. Testing Requirements/Design +### 1.13. Testing Requirements/Design Explain what kind of unit testing, system testing, regression testing, warmboot/fastboot testing, etc., Ensure that the existing warmboot/fastboot requirements are met. For example, if the current warmboot feature expects maximum of 1 second or zero second data disruption, the same should be met even after the new feature/enhancement is implemented. Explain the same here. Example sub-sections for unit test cases and system test cases are given below. -#### 1.13.1. Unit Test cases +#### 1.13.1. Unit Test cases - Configuration – good flow - Verify default values - Configure all types and check updated values - Configure authentication_retries to X and try to connect with wrong password X+1 times - Configure login_timeout to X, try to connect and wait for X+5 seconds (need to disconnect) - Configure ports to 222 and see if unable to connect to 22 + - Configure inactivity_timeout to X, login and wait for X+5 seconds (need to disconnect) + - Configure max_syslogins to X and see if unable to login to X+1 concurrent sessions -#### 1.13.2. System Test cases +#### 1.13.2. System Test cases -### 1.14. Open/Action items - if any +### 1.14. Open/Action items - if any NOTE: All the sections and sub-sections given above are mandatory in the design document. Users can add additional sections/sub-sections if required.