SONiC/cheatsheet

== OSS SONiC ==
=== Software upgrades ===
Daily images for each branches are available on : https://sonic-build.azurewebsites.net/ui/sonic/Pipelines
=== Run commands from the MGMT vrf ===
Prepend the command with sudo ip vrf exec mgmt, for example sudo ip vrf exec mgmt ping apt.wikimedia.org
=== Configuration ===
All configuration is stored in a Redis database, wrappers to the various Redis tools are provided for SONiC specific operations. It's usually not recommended to mess directly with the database but to use the provided abstraction layers.
The sonic-cli (more recent) abstraction layer is very limited. The recommended path is to use the sudo config <command> tool. Which is slow but supports tab completion and --help.
sudo config save -y writes the config to: /etc/sonic/config_db.json
=== Database Operations ===
Unfortunately it's sometime needed to directly interact with the DB.
==== Dumping DB ====
===== JSON =====
sonic-db-dump -y -n CONFIG_DB -k 'SECURITY_PROFILES|default'
Globbing (*) is supported for the keys (-k).
removing the -k parameter shows the whole running config.
===== Key/value =====
sonic-db-cli CONFIG_DB hgetall 'SECURITY_PROFILES|default'
==== Writing data ====
sonic-db-cli CONFIG_DB hmset 'SECURITY_PROFILES|default' certificate-name default
===== Deleting data =====
sonic-db-cli CONFIG_DB hdel 'SECURITY_PROFILES|default' NULL
=== Docker ===
Most functional areas (daemons, protocols) run as docker containers. So regular docker commands work (docker ps, docker exec, docker inspect)
Those images load files and config by mounting host filesystems directory, and interact directly with the Redis database.
To know exactly what a container does and which files or DB keys control its behavior it's often needed to dig into it.
==== For example, which DB keys control the gNMI daemon and where do the cert/key files need to be located ? ====
docker inspect gnmi shows that /etc/sonic/ is mounted in the container, and /usr/local/bin/supervisord is executed.
docker exec gnmi cat /etc/supervisor/conf.d/supervisord.conf then docker exec gnmi cat /usr/bin/gnmi-native.sh show the sequence of events and DB keys used to configure the gnmi daemon.
=== Users management ===
Linux command line is used to manage users.
To add a user as admin :
sudo useradd -s /bin/bash -m -G sudo,docker,redis <username>
Then either set the user password with : sudo passwd <username>, or copy the user's public SSH key to /home/<username>/.ssh/authorized_keys
=== gNMI ===
Only supports a few standard models, which are not fully implemented
* openconfig-acl
* openconfig-sampling-sflow
* openconfig-acl
* openconfig-interfaces
* openconfig-lldp
* openconfig-platform
* openconfig-system
* ietf-yang-library
For example it's not possible to request a specific DataType :
$ gnmic --config test.yaml get --path interfaces -t CONFIG
target "lsw1-f8-eqiad.mgmt.eqiad.wmnet:8080" get request failed: "lsw1-f8-eqiad.mgmt.eqiad.wmnet:8080" GetRequest failed: rpc error: code = Unimplemented desc = unsupported request type: CONFIG
It also implements a SONiC specific sonic-db model, which is also known as "native" as it manipulated the Sonic DB directly (in opposition to having to use an intermediary lib named "translib").
This model exposes directly the SONiC database, to use it you need to refer to the schema definition and optionally config_db.json
For example to query the BGP peers:
gnmic --config test.yaml get --target CONFIG_DB --path BGP_NEIGHBOR
To query the routing table :
gnmic --config test.yaml get --target STATE_DB --path ROUTE_TABLE
Not all paths seem to work though, for example FDB_TABLE fails with code = NotFound desc = Failed to find STATE_DB FDB_TABLE
==== Set ====
Native write operations fail with a "Translib" error. Note that Translib write can only be enabled during the image build time.
$ gnmic --config test.yaml set --target CONFIG_DB --update-path DNS_NAMESERVER --update-value {'10.3.0.1':{}. '8.8.8.8':{}}
target "lsw1-f8-eqiad.mgmt.eqiad.wmnet:8080" set request failed: target "lsw1-f8-eqiad.mgmt.eqiad.wmnet:8080" SetRequest failed: rpc error: code = Unimplemented desc = Translib write is disabled
==== See also ====
https://github.com/sonic-net/sonic-gnmi/blob/master/doc/grpc_telemetry.md
https://karneliuk.com/2023/01/automation-19-enabling-ocp-sonic-to-be-managed-via-gnmi-with-pygnmi/
https://github.com/mfzhsn/sonic-telemetry
=== RESTCONF ===
Models description (from YANG) are visible in https://<fqdn>/ui/
For example curl -X GET "https://<fqdn>/restconf/data/openconfig-interfaces:interfaces" -H  "accept: application/yang-data+json" returns all the interfaces.
But also curl -X GET "https://localhost:8443/restconf/data/openconfig-system:system" -H  "accept: application/yang-data+json" fails with
{
 "ietf-restconf:errors": {
 "error": [
 {
 "error-type": "application",
 "error-tag": "operation-failed"
 }
 ]
 }
}
=== See also ===
https://github.com/sonic-net/sonic-utilities/blob/master/doc/Command-Reference.md
Written by SuperMicro, but for SONiC nonetheless : https://www.supermicro.com/manuals/network/Supermicro_Datacenter_SONiC_Configuration_Guide.pdf
== Dell SONiC ==
=== Configuration ===
sonic-cli supports most of the configuration actions needed, and all of the day to day configuration changes one could do.
When typing "write memory" in sonic-cli a dump of the config database is written to: /etc/sonic/config_db.json
=== Software upgrade ===
Copy the new image to usual apt server aptXXXX:/srv/sonic/
In sonic-cli
# Run the install with image install https://aptXXXX/sonic/Enterprise_SONiC_OS_xxx_Enterprise_Standard.bin
# Monitor the progress with show image status
# Once done (Global operation status  : GLOBAL_STATE_SUCCESS) reboot with reboot
==== Cleanup ====
In sonic-cli
# List the existing images with show image list
# Delete the old one with image remove SONiC-OS-xxxx
=== gNMI ===
All gNMI operations use standardized openconfig models, and support DataTypes.
=== TLS certificate operations ===
The sre.network.tls cookbook does the right thing in term of refresh.
For the inital setup those manual steps are still needed after running the sre.network.tls cookbook (to be eventually integrated to the cookbook):
Unlike OSS SONiC, Dell SONiC uses SECURITY_PROFILES.
sonic-db-cli CONFIG_DB hmset 'SECURITY_PROFILES|default' profile-name default
sonic-db-cli CONFIG_DB hmset 'SECURITY_PROFILES|default' certificate-name default
sonic-db-cli CONFIG_DB hmset 'TELEMETRY|gnmi' security_profile default
sudo ln -s /etc/sonic/cert/host/default.crt /etc/sonic/cert/host/default
sudo ln -s /etc/sonic/cert/keys/default.key /etc/sonic/cert/keys/default
This is similar to using the sonic-cli actions.
=== User management ===
sonic-cli is used to managed users. ssh-keys are not yet supported, see also https://phabricator.wikimedia.org/T338028
=== Doc ===
https://infohub.delltechnologies.com/en-US/t/enterprise-sonic-distribution-by-dell-technologies-lifecycle-management/