Celestica Open Source Network
“
Product Information
Specifications
- Product Name: SONiC
- Operating System: SONiC NOS
- Installation Methods: USB Thumb Drive, Network
Installation - User Interface: Command Line Interface (CLI)
- Version: Variable based on download
Product Usage Instructions
1. Download Image
Download the SONiC NOS image from the official website.
2. Installation using a USB Thumb Drive
Insert the USB thumb drive with the SONiC NOS image into the
device. Follow on-screen instructions to install the image.
3. Installation Over The Network
Connect the device to the network and follow the steps to
install SONiC NOS over the network.
4. Login Username and Password
Use the default login credentials provided in the manual to
access the system.
5. Basic Configuration and Show
Configure management and loopback interfaces as needed. Use
‘show’ commands to display system information.
6. Software Version and Upgrade
Check the current software version and upgrade if necessary.
Follow instructions for upgrading or downgrading versions.
7. SONiC Installer
Utilize the SONiC installer for system setup and
configuration.
8. Startup Configuration
View and modify startup configurations to customize system
settings.
9. Troubleshooting
Use basic troubleshooting commands like ‘show techsupport’,
‘syslog’, and ‘tcpdump’ to diagnose issues.
FAQ
Q: What are the default login credentials for SONiC?
A: The default login username is provided in the manual as
‘admin’ with a password of ‘admin123’.
Q: How can I upgrade the software version of SONiC?
A: To upgrade the software version, download the latest image
from the official website and follow the upgrade instructions
provided in the manual.
“`
SONiC User Manual
Table of Contents
SONiC User Manual …………………………………………………………………………………………1 Introduction ……………………………………………………………………………………………………….. 2 Quick Start ………………………………………………………………………………………………………….4
Download Image ………………………………………………………………………………………………4
Installation using a USB Thumb Drive………………………………………………………………4 Installation Over The Network…………………………………………………………………………4
Fresh Installation of SONiC NOS……………………………………………………………….4 Install SONiC NOS Image …………………………………………………………………………6
Login Username and Password …………………………………………………………………..8
Default Login ……………………………………………………………………………………………………8 Configuring Username and Password …………………………………………………………….. 9
Basic Configuration and Show……………………………………………………………………10
Configuring Management Interface and Loopback Interface ………………………..10 Software Version and Upgrade ………………………………………………………………………11
Show Versions…………………………………………………………………………………………….12 Available Features in this Version ………………………………………………………………….13 Upgrade Or Downgrade Version …………………………………………………………………….13
SONiC Installer ……………………………………………………………………………………..13
Startup Configuration…………………………………………………………………………………….. 15
Default Startup Configuration ……………………………………………………………………….15 Modify Configuration…………………………………………………………………………………… 16
Modify config_db.json …………………………………………………………………………… 16
Troubleshooting……………………………………………………………………………………………… 17
Basic Troubleshooting Commands ………………………………………………………………..17
show techsupport ……………………………………………………………………………………….17 syslog ………………………………………………………………………………………………………..18 tcpdump …………………………………………………………………………………………………….18
i
Contact Information ………………………………………………………………………………………19
ii
SONiC User Manual
This reference document provides important legal disclaimers and notices for SONiC products.
Disclaimer
Copyright © 2024 by Celestica. All Rights Reserved. “Celestica” refers to Celestica Inc. and its subsidiaries. For additional information, please visit our website at www.Celestica.com. All trademarks, trade names, service marks, and logos mentioned belong to their respective owners. Celestica may update product specifications or information without prior notice to enhance reliability, functionality, or design. Although the provided information is believed to be accurate, no responsibility is assumed for its use, or for any infringements of patents or third-party rights.
1
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 preloaded 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.
1. Command Line Interface 2. 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:
1. How to load the SONiC image on the supported platforms. 2. How to login using default username and password, how to change password, how to
configure management interface and Loopback address configuration. 3. 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. 4. 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. 5. 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
2
other configuration documents (like Command Reference, Config DB Manual, Troubleshooting Guide, and so on). Refer the corresponding documents for detailed information.
3
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.
4
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 commandline.
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
|
5
| 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 filesystem using:
sudo sonic-installer install sonic-broadcom.bin
6
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
7
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.
8
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
9
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.
{
10
“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
11
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, 1.93, 1.97 Date: Fri 20 Sep 2024 09:20:22
load average: 1.80,
12
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 sonicinstaller 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
13
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-OScelestica_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
14
root@Celestica-DS1000:~# sonic-installer set-next-boot SONiC-OScelestica_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-OScelestica_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.
1. DEVICE_METADATA 2. MAP_PFC_PRIORITY_TO_QUEUE 3. QUEUE 4. PORT
15
5. CRM 6. PORT_QOS_MAP 7. NTP_SERVER 8. BUFFER_QUEUE 9. WRED_PROFILE 10. TC_TO_PRIORITY_GROUP_MAP 11. BUFFER_PROFILE 12. DEVICE_NEIGHBOR 13. DSCP_TO_TC_MAP 14. TC_TO_QUEUE_MAP 15. CABLE_LENGTH 16. SCHEDULER 17. 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.
16
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
17
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
18
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.
19
Documents / Resources
 |
SONiC Celestica Open Source Network [pdf] User Manual Celestica, Celestica Open Source Network, Open Source Network, Network |
