SONiC User Manual

Introduction

SONiC is an open source network operating system based on Linux that runs on switches from multiple vendors and ASICs (Application Specific Integrated Circuits). SONiC offers a full-suite of network functionality, like BGP and RDMA, that has been production-hardened in the data centers of some of the largest cloud-service providers. It offers teams the flexibility to create the network solutions they need while leveraging the collective strength of a large ecosystem and community.

SONiC software shall be loaded in these supported devices and this User guide explains the basic steps for using the SONiC in those platforms.

Connect the console port of the device and use the 115200 baud rate to access the device. Follow the Quick Start Guide to boot the device in ONIE mode and install the SONiC software using the steps specified in the document and reboot the device. In some devices that are pre-loaded with SONiC software, this step can be skipped. Users shall use the default username/ password "admin/YourPaSsWoRd" to login to the device through the console port.

After logging into the device, SONiC software can be configured in following two methods:

• Command Line Interface
• config_db.json

Users can use all of the above methods or choose either one method to configure and to view the status of the device. This user manual explains the common commands and related configuration/show examples on how to use the SONiC device. Refer the above documents for more detailed information.

Document Scope

Information in this manual is based on the SONiC software version 202311. This user manual provides some insights on the following:

• How to load the SONiC image on the supported platforms.
• How to login using default username and password, how to change password, how to configure management interface and Loopback address configuration.
• How to check the software version running on the device, how to check the list of features available in this software version, how to upgrade to new software version, and so on.
• How to check the default startup configuration with which the device is currently running, how to load a new configuration to this device, and so on.
• Basic information about troubleshooting and the link to the detailed troubleshooting guide.

Note that some parts of this document might be a repetition of few commands/paragraphs from other configuration documents (like Command Reference, Config DB Manual, Troubleshooting Guide, and so on). Refer the corresponding documents for detailed information.

Quick Start

This section details the steps to install a SONiC image on your supported switch.

Download Image

We have one SONiC Image per ASIC vendor. You can download SONiC Image here. You can also build SONiC from source and the instructions can be found here. Once the image is available in your local machine, the image can be installed either by installing using a USB thumb drive or over the network as given in following sub-sections. In case if the device is already preloaded with SONiC image, the device can be booted without the installation process.

Installation using a USB Thumb Drive

This section explains how to transfer the image from an USB thumb drive into the device and install it.

1. Copy the downloaded SONiC image on the USB thumb drive.
2. Remove the USB drive from your machine and insert it into the USB port on the front (or rear) panel of your ONIE enabled device.
3. Power on the device and ONIE will discover the onie-installer file on the root of the USB drive and execute it.

The above information is taken from https://opencomputeproject.github.io/onie/user-guide/index.html

Installation Over The Network

This section explains how to transfer the image from remote server into the device and install it.

Fresh Installation of SONiC NOS

1. Connect to switch via serial console.
2. For ARM platforms, use run onie_bootcmd from UBOOT prompt to load ONIE.
3. (Optional) Some switches may come with a NOS which will require you to uninstall the existing NOS first before you install SONiC. To do so, simply boot into ONIE and select Uninstall OS.

GNU GRUB version 2.02~beta2+e4a1fe391
+-------------------------------------------------------------------------
---+
|*ONIE: Install
OS
|
| ONIE:
Rescue
|
| ONIE: Uninstall OS <----- Select this
one
|
| ONIE: Update
ONIE
|
| ONIE: Embed
ONIE
|
+--------------------------------------------------------------------------+

Use the ^ and v keys to select which entry is highlighted. Press enter to boot the selected OS, `e' to edit the commands before booting or `c' for a command-line.

4. Reboot the switch into ONIE and select Install OS.

GNU GRUB version 2.02~beta2+e4a1fe391
+-------------------------------------------------------------------------
---+
|*ONIE: Install OS <----- Select this
one
|
| ONIE:
Rescue
|
| ONIE: Uninstall
OS
|
| ONIE: Update
ONIE
|
| ONIE: Embed
ONIE
|
+---------------------------------------------------------------------------+

Use the ^ and v keys to select which entry is highlighted. Press enter to boot the selected OS, `e' to edit the commands before booting or `c' for a command-line.

5. Assign IP address. Ensure that eth0 is assigned a static IP or via DHCP. For ES1000 x86, ensure eth2 is assigned a static IP or via DHCP. For ES1010/ES1050/EG1050, ensure eth2 is assigned a static IP or via DHCP. Stop ONIE discovery mode using onie-stop.

Note: ES1000 x86 and ES1010/ES1050/EG1050 ONIE eth2 is considered as Management interface.

6. Install SONiC. Transfer the image into the device using scp / sftp / ftp / http.

ONIE:/ # ifconfig eth0 <ip_address> netmask <netmask_ip>
ONIE:/ # ip route add default <gateway_ip>
ONIE:/ # onie-nos-install <URL>

7. After installation is successful, the device will reboot automatically and boot-up with SONiC.

Install SONiC NOS Image

1. Install the NOS. Install the sonic-broadcom.bin using sonic-installer command. sonic-broadcom.bin file should have been already transferred to the sonic file-system using:

sudo sonic-installer install sonic-broadcom.bin

Note: Alternatively, the image can be placed in a remote http server and sonic_installer command can be used after providing the http file location.

2. Check the Image status. Check the image status by using the following command.

sudo sonic-installer list

The newly installed image should show up under "Next:" where,

• Current : refers to current running image.
• Next : refers to next boot up image.
• Available : refers to all installed SONiC images.

3. Reboot. After installation, reboot the system and the new image should appear as one of the NOS install options (which is also the default).

sudo reboot

Login Username and Password

This section explains the default username and password and how to change the password.

Default Login

By default, all SONiC devices support both the serial console based login and the SSH based login. The default credential (if not modified at image build time) for login is admin/ YourPaSsWoRd. In case of SSH login, users can login to the management interface (eth0) IP address after configuring the same using serial console. Refer the Configuring Management Interface and Loopback Interface section for configuring the IP address for management interface.

Example:

At Console: Debian GNU/Linux 9 sonic ttyS1
sonic login: admin
Password: YourPaSsWoRd

SSH from any remote server to sonic can be done by connecting to SONiC IP
user@debug:~$ ssh admin@sonic_ip_address(or SONIC DNS Name)
admin@sonic's password:

By default, login takes the user to the default prompt from which all the show commands can be executed. On successful login, SONiC Welcome Message of the Day will be displayed.

You are on
SONIC
-- Software for Open Networking in the Cloud --
Celestica
Unauthorized access and/or use are prohibited.
All access and/or use are subject to monitoring.
Help:
https://sonic-net.github.io/SONiC/

Configuring Username and Password

Note: Wait for the System is ready to be displayed before login. First time login will prompt the user to change the password. Enter a new password that meets the password policy requirements. This password cannot be the same as the default password.

By default, ZTP will be enabled (For ES1000 ARM platform, ZTP is disabled by default). User has to disable ZTP using sudo config ztp disable (This will take approximately 2 minutes)

Update the new password using the Click CLI.

config user modify admin --password <password>

The new password will be saved into startup configuration only when the configuration is saved. To save the running configuration into startup configuration, use the following CLI command.

sudo config save -y

Basic Configuration and Show

SONiC is managing the configuration in a single source of truth, a redisDB instance that we refer as ConfigDB. The applications subscribe to ConfigDB and generate their running configuration correspondingly. You can find the details about ConfigDB and schema design here. SONiC includes commands that allow user to show platform, transceivers, L2, IP, BGP status, and so on.

Command Reference

Note: All the configuration commands require root privileges to execute them and the commands are case-sensitive. Show commands can be executed by all users without the root privileges. Root privileges can be obtained either by using sudo keyword in front of all config commands, or by going to root prompt using sudo -i .

Configuring Management Interface and Loopback Interface

The management interface (eth0) in SONiC is configured (by default) to use DHCP client to get the IP address from the DHCP server. Connect the management interface to the same network in which your DHCP server is connected and get the IP address from DHCP server. The IP address received from DHCP server can be verified using the /sbin/ifconfig eth0 Linux command.

There are few alternate ways by which a static IP address can be configured for the management interface.

1. Use Click CLI.

admin@Celestica-DS1000:~$ config interface ip add eth0 <ip_addr> <default gateway IP>

2. Use config_db.json and configure the MGMT_INTERFACE key with the appropriate values. For details, refer here Add the following example configuration in a file (example: mgmt_ip.json) and load it as follows.

{
  "MGMT_INTERFACE|eth0|10.208.81.132/24": {
    "value": {
      "gwaddr": "10.208.81.1"
    }
  }
}

Note: If the interface IP address and default gateway were already present, users should remove them before loading the above configuration.

Users can either use the show running configuration all command to check the already configured MGMT_INTERFACE or the redis-cli command as follows to check the same.

admin@Celestica-DS1000:~$ redis-cli -n 4 keys "MGMT_INTERFACE*"
1) "MGMT_INTERFACE|eth0|10.208.81.132/24"
admin@Celestica-DS1000:~$

After removing the key, users can load the new configuration using the config load mgmt_ip.json command and then do systemctl restart interfaces-config to make it effective. Users shall verify the configured management interface IP address value using the ifconfig Linux command or show ip interfaces through click CLI.

3. Once the IP address is configured, the same can be verified using the /sbin/ifconfig eth0 Linux command. Users can SSH login to this management interface IP address from their management network.

Example:

admin@sonic:~$ /sbin/ifconfig eth0
eth0: flags=4163 mtu 1500
inet 10.11.11.13 netmask 255.255.255.0 broadcast 10.11.12.255

The same method can be used to configure the Loopback interface address.

1. /sbin/ifconfig lo Linux command shall be used. OR,
2. Add the key LOOPBACK_INTERFACE and value in config_db.json and load it.

Software Version and Upgrade

This section explains how to check the current version of the software running in the device, how to check the features available in the version and how to upgrade/downgrade to different versions.

Show Versions

show version

This command displays software component versions of the currently running SONiC image. This includes the SONiC image version as well as Docker image versions. This command displays relevant information as the SONiC and Linux kernel version being utilized, as well as the commit-id used to build the SONiC image.

Usage

show version

Example

root@Celestica-DS1000:~$ show version
SONiC Software Version: SONiC-OS-celestica_sonic_3.1.2-5-8f2ee6619
Product: Celestica DS1000
SONiC OS Version: 11
Distribution: Debian 11.11
Kernel: 5.10.0-23-2-amd64
Build commit: 8f2ee6619
Build date: Mon Sep 16 19:00:57 UTC 2024
Built by: autobuild@AZUHPSP10

Platform: x86_64-cel_ds1000-r0
HwSKU:
Celestica DS1000
ASIC: broadcom
ASIC Count: 1
Serial Number: E1070F2B042525GD200121
Model Number: R3059-F9010-01
Hardware Revision: 4
Uptime: 09:20:22 up 3 days, 31 min, 2 users, load average: 1.80,
1.93, 1.97
Date: Fri 20 Sep 2024 09:20:22

Available Features in this Version

SONiC roadmap planning explains the various features that are added in every software release.

Upgrade Or Downgrade Version

SONiC software can be installed in two methods, either by using ONIE Installer or by using sonic-installer tool. ONIE Installer can be used as explained in the QuickStartGuide. sonic-installer tool can be used as explained below.

SONiC Installer

This is a command line tool available as part of the SONiC software. If the device is already running the SONiC software, this tool can be used to install an alternate image in the partition. This tool has facility to install an alternate image, list the available images and to set the next reboot image.

sonic-installer install

This command is used to install a new image on the alternate image partition. This command takes a path to an installable SONiC image or URL and installs the image.

Note: To avoid retaining configuration while switching to latest version of SONiC or other variants, use sonic-installer install --skip_migration --skip-package-migration sonic-broadcom.bin

Usage

sonic-installer install

Example

root@Celestica-DS1000:~$ sonic-installer install sonic-broadcom.bin

sonic-installer list

This command displays information about currently installed images. It displays a list of installed images, currently running image and image set to be loaded in next reboot.

Usage

sonic-installer list

Example

root@Celestica-DS1000:~# sonic-installer list
Current: SONiC-OS-celestica_sonic_3.1.2-5-8f2ee6619
Next: SONiC-OS-celestica_sonic_3.1.2-6-568c05804
Available:
SONiC-OS-celestica_sonic_3.1.2-6-568c05804
SONiC-OS-celestica_sonic_3.1.2-5-8f2ee6619
root@Celestica-DS1000:~#

sonic-installer set-default

This command is used to change the image that can be loaded by default in all the subsequent reboots.

Usage

sonic-installer set-default <image_name>

Example

root@Celestica-DS1000:~$ sonic-installer set-default SONiC-OS-
celestica_sonic_3.1.2-6-568c05804

sonic-installer set-next-boot

This command is used to change the image that can be loaded in the next reboot only. Note that it will fallback to current image in all other subsequent reboots after the next reboot.

Usage

sonic-installer set-next-boot <image_name>

Example

root@Celestica-DS1000:~$ sonic-installer set-next-boot SONiC-OS-
celestica_sonic_3.1.2-6-568c05804^C

sonic-installer remove

This command is used to remove the unused SONiC image from the disk. Note that it is not allowed to remove currently running image.

Usage

sonic-installer remove <image_name>

Example

root@Celestica-DS1000:~$ sonic-installer remove SONiC-OS-
celestica_sonic_3.1.2-6-568c05804

Go Back to Beginning of the document or Beginning of this section.

Startup Configuration

This section explains how to check the default startup configuration with which the device is currently running and how to load a new configuration to this device.

Default Startup Configuration

Users can use the show running configuration command to check the current running configuration. If users have not done any configuration change after the reboot, this will be same as the default startup configuration. SONiC device contains the startup configuration in the file /etc/sonic/config_db.json. During reboot, this configuration will be loaded by default. Following are some of the keys that are configured by default in the config_db.json.

• DEVICE_METADATA
• MAP_PFC_PRIORITY_TO_QUEUE
• QUEUE
• PORT
• CRM
• PORT_QOS_MAP
• NTP_SERVER
• BUFFER_QUEUE
• WRED_PROFILE
• TC_TO_PRIORITY_GROUP_MAP
• BUFFER_PROFILE
• DEVICE_NEIGHBOR
• DSCP_TO_TC_MAP
• TC_TO_QUEUE_MAP
• CABLE_LENGTH
• SCHEDULER
• BUFFER_POOL

Modify Configuration

Modify config_db.json

Users can directly edit and modify the file /etc/sonic/config_db.json or do a SCP and copy this file from a remote server. User can either do config reload command to load this new configuration, or users can simply reboot to make it effective.

Troubleshooting

This section captures some of the frequently used troubleshooting commands and methods. Users can refer the Troubleshooting Guide for more details about troubleshooting.

Basic Troubleshooting Commands

Users can use the following commands/functionalities:

• show techsupport command to collect the information from the device.
• Syslog to view the syslogs printed by the services.
• Linux utilities like ping, tcpdump, and so on to check the connectivity and packet tracing.

show techsupport

This command gathers pertinent information about the state of the device. Information is as diverse as syslog entries, database state, routing-stack state, and so on. It then compresses the information into an archive file. This archive file can be sent to the SONiC development team for examination. Resulting archive file is saved as /var/ dump/<DEVICE_HOST_NAME>_YYYYMMDD_HHMMSS.tar.gz

Some of the details that the dump includes are given below:

• Interface details
• Platform details
• Machine.conf
• Vlan configs
• Routes
• Sensor, transceiver details
• Syslog
• Ip configs
• Bgp details
• Device Configs (json/ minigraph)

Usage

show techsupport

Example

admin@Celestica-DS1000:~$ show techsupport

syslog

System logs and event messages from all dockers are captured through syslog and saved in /var/log/syslog

Console logs can be viewed using the show logging command also. This command prints the information in syslog in console.

show logging -f will tail the output of syslogs in console/ssh session.

tcpdump

tcpdump is a common packet analyzer that runs under the sonic command line. It allows the user to display TCP/IP and other packets being transmitted or received over a network. Example: tcpdump -i Ethernet0

Contact Information

Celestica operates a customer service portal. Self-support resources (knowledge base, FAQ, common fixes, new firmware) are available. Our support teams are connected to the support portal and can receive notifications for requests. The portal also tracks and collects customer inputs for further improvements to our products and services.

Customers can register and request support (as well as search information in the knowledge base) at: https://customersupport.celestica.com/csm

In case there are any questions or issues using the customer portal visit: https://www.celestica.com/contact-us. For immediate questions, please feel free to call your responsible account manager.