description [text]
The 'description' command in interface configuration mode adds a text description to an interface to identify its purpose, connection, or other administrative information, aiding in documentation and troubleshooting.
Definition: description [text] is a Cisco IOS interface config command. The 'description' command in interface configuration mode adds a text description to an interface to identify its purpose, connection, or other administrative information, aiding in documentation and troubleshooting.
Overview
The 'description' command in interface configuration mode is a fundamental tool for network documentation and troubleshooting. It allows administrators to attach a human-readable text string to an interface, such as 'Link to Core Switch A' or 'Customer VLAN 100 uplink'. This metadata is stored in the running configuration and appears in show commands like 'show running-config interface' or 'show interfaces description'.
The primary purpose is to improve operational clarity: when multiple interfaces exist, descriptions help engineers quickly identify the purpose or connection of each interface without relying on IP addresses or external documentation. This is especially critical in large enterprise networks where misconfiguration or outages require rapid diagnosis. The command itself is simple—no parameters beyond the text string—but its impact on network management is profound.
It fits into the broader workflow of configuration management and change control: before making changes, engineers should verify interface descriptions to ensure they are modifying the correct interface. In troubleshooting, descriptions provide immediate context; for example, a description like 'Uplink to ISP - Primary' immediately indicates the interface's role. Alternatives include using the 'name' command on VLAN interfaces or relying on SNMP sysName, but 'description' is the most direct and universally supported method across Cisco IOS platforms.
There are no privilege level requirements beyond interface configuration mode (typically privilege level 15), and the command immediately updates the running configuration. Descriptions are saved to NVRAM with 'write memory' and persist across reloads. A common pitfall is forgetting to update descriptions after topology changes, leading to stale or misleading information.
Best practice dictates that every production interface should have a meaningful description, and organizations often enforce this via configuration templates or audits. The command supports up to 240 characters, though shorter descriptions are recommended for readability. In summary, the 'description' command is a simple but powerful tool for network documentation, directly supporting operational excellence and reducing mean time to resolution (MTTR) during incidents.
description [text]When to Use This Command
- Labeling a router interface connected to a specific customer or site, e.g., 'Link to HQ'.
- Documenting the type of connection or circuit ID on a WAN interface, e.g., 'T1 Circuit #12345'.
- Noting the VLAN or subnet assigned to a switch interface, e.g., 'VLAN 10 - Sales'.
- Marking an interface as a backup or failover link, e.g., 'Backup link to DR site'.
Parameters
| Parameter | Syntax | Description |
|---|---|---|
| text | LINE | A text string up to 240 characters that describes the interface. It can include letters, numbers, spaces, and punctuation. Common mistakes include using special characters that may be misinterpreted (though most are allowed) or exceeding the character limit, which causes the command to be truncated. Always enclose the text in quotes if it contains leading/trailing spaces or special characters, though quotes are not required for simple strings. |
Command Examples
Basic Interface Description
Router(config-if)# description Link to HQ - GigabitEthernet0/0No output is generated by the 'description' command itself. The description is stored in the running configuration and can be viewed with 'show interfaces' or 'show running-config'. This example sets a description for GigabitEthernet0/0 indicating it connects to HQ.
Verifying Description in Show Output
Router# show interfaces GigabitEthernet0/0GigabitEthernet0/0 is up, line protocol is up
Hardware is CN Gigabit Ethernet, address is 0011.2233.4455 (bia 0011.2233.4455)
Description: Link to HQ - GigabitEthernet0/0
Internet address is 192.168.1.1/30
MTU 1500 bytes, BW 1000000 Kbit/sec, DLY 10 usec,
reliability 255/255, txload 1/255, rxload 1/255
Encapsulation ARPA, loopback not set
Keepalive set (10 sec)
Full Duplex, 1000Mbps, media type is RJ45
output flow-control is unsupported, input flow-control is unsupported
ARP type: ARPA, ARP Timeout 04:00:00
Last input 00:00:00, output 00:00:00, output hang never
Last clearing of "show interface" counters never
Input queue: 0/75/0/0 (size/max/drops/flushes); Total output drops: 0
Queueing strategy: fifo
Output queue: 0/40 (size/max)
5 minute input rate 0 bits/sec, 0 packets/sec
5 minute output rate 0 bits/sec, 0 packets/sec
0 packets input, 0 bytes, 0 no buffer
Received 0 broadcasts (0 IP multicasts)
0 runts, 0 giants, 0 throttles
0 input errors, 0 CRC, 0 frame, 0 overrun, 0 ignored
0 watchdog, 0 multicast, 0 pause input
0 input packets with dribble condition detected
0 packets output, 0 bytes, 0 underruns
0 output errors, 0 collisions, 1 interface resets
0 unknown protocol drops
0 babbles, 0 late collision, 0 deferred
0 lost carrier, 0 no carrier, 0 pause output
0 output buffer failures, 0 output buffers swapped outThe 'show interfaces' output includes a line 'Description: Link to HQ - GigabitEthernet0/0' that displays the configured description. This helps identify the interface's purpose without needing to check the configuration file. The rest of the output shows interface status, IP address, MTU, bandwidth, reliability, load, encapsulation, duplex, speed, and counters for errors and traffic.
Understanding the Output
The 'description' command itself produces no output. To view the description, use 'show interfaces' or 'show running-config'. In 'show interfaces', the description appears on a line starting with 'Description:'.
This field is purely administrative and does not affect interface operation. A missing or generic description (e.g., 'Description:') indicates the interface has not been documented. Good practice is to include meaningful text that helps network engineers quickly understand the interface's role, such as the connected device, location, or circuit ID.
Watch for descriptions that are too long (max 240 characters) or contain special characters that might cause parsing issues in scripts.
Configuration Scenarios
Documenting a WAN uplink to a service provider
A network engineer needs to identify the primary and backup WAN connections on a branch router. Adding descriptions helps distinguish the two links and provides contact information for the provider.
Topology
Branch-Router(Gi0/0)---10.0.1.0/30---(Gi0/0)ISP-Router
Branch-Router(Gi0/1)---10.0.2.0/30---(Gi0/1)ISP-RouterSteps
- 1.Step 1: Enter global configuration mode: configure terminal
- 2.Step 2: Enter interface configuration mode for Gi0/0: interface GigabitEthernet0/0
- 3.Step 3: Add a description: description Primary WAN link to ISP-A (Circuit ID: 12345)
- 4.Step 4: Exit and repeat for Gi0/1: interface GigabitEthernet0/1
- 5.Step 5: Add description for backup: description Backup WAN link to ISP-B (Circuit ID: 67890)
- 6.Step 6: Exit configuration mode and save: end, write memory
! Configuration for Branch-Router interface GigabitEthernet0/0 description Primary WAN link to ISP-A (Circuit ID: 12345) ip address 10.0.1.2 255.255.255.252 ! interface GigabitEthernet0/1 description Backup WAN link to ISP-B (Circuit ID: 67890) ip address 10.0.2.2 255.255.255.252 !
Verify: Use 'show interfaces description' to verify. Expected output shows both interfaces with their descriptions and status. Example: Interface Status Protocol Description Gi0/0 up up Primary WAN link to ISP-A (Circuit ID: 12345) Gi0/1 up up Backup WAN link to ISP-B (Circuit ID: 67890)
Watch out: A common mistake is forgetting to update the description when the circuit ID changes or when the link role changes (e.g., backup becomes primary). Always review descriptions during change management.
Labeling a trunk interface connecting to a distribution switch
An access switch connects to a distribution switch via a trunk port. The description should indicate the connected device and the VLANs allowed, aiding in troubleshooting connectivity issues.
Topology
Access-Switch(Gi0/24)---Trunk---(Gi0/1)Dist-SwitchSteps
- 1.Step 1: Enter global configuration mode: configure terminal
- 2.Step 2: Enter interface configuration mode for Gi0/24: interface GigabitEthernet0/24
- 3.Step 3: Add a description: description Trunk to Dist-Switch Gi0/1 - Allowed VLANs 10,20,30
- 4.Step 4: Configure trunking: switchport mode trunk, switchport trunk allowed vlan 10,20,30
- 5.Step 5: Exit and save: end, write memory
! Configuration for Access-Switch interface GigabitEthernet0/24 description Trunk to Dist-Switch Gi0/1 - Allowed VLANs 10,20,30 switchport mode trunk switchport trunk allowed vlan 10,20,30 !
Verify: Use 'show interfaces description' or 'show running-config interface GigabitEthernet0/24'. The description should appear in the output. Also 'show interfaces trunk' to verify trunk status.
Watch out: If the description includes VLAN information, it must be updated whenever the allowed VLAN list changes. Otherwise, the description becomes misleading. Also, ensure the description does not contain sensitive information like passwords.
Troubleshooting with This Command
The 'description' command is primarily a documentation tool, but it plays a crucial role in troubleshooting by providing immediate context. When an interface is down or experiencing errors, the description can tell you what the interface is supposed to connect to, which helps narrow down the problem. For example, if a description reads 'Uplink to Core Switch A' and the interface is down, you know to check the physical connection to Core Switch A.
Healthy output from 'show interfaces description' shows all interfaces with their status (up/up, up/down, administratively down) and descriptions. Problem indicators include missing descriptions (empty field) or descriptions that are outdated (e.g., still referencing a device that has been replaced). Focus on interfaces that are up/down or down/down; the description helps identify the affected segment.
Common symptoms: an interface is down but the description says 'Uplink to Backup ISP' — this might indicate a failover event. Step-by-step diagnostic flow: 1) Use 'show interfaces description' to get a quick overview of all interfaces and their status. 2) For any interface that is not up/up, note its description. 3) If the description indicates a critical link, investigate further with 'show interfaces [interface]' for detailed error counters. 4) Correlate with other show commands: for example, if a trunk interface is down, use 'show interfaces trunk' to see if the trunk is misconfigured. The description can also be used in scripts or monitoring tools to generate alerts; for instance, if an interface with 'WAN' in its description goes down, trigger a high-priority alert.
In summary, while 'description' does not directly diagnose faults, it provides essential context that speeds up troubleshooting and reduces human error.
CCNA Exam Tips
CCNA exam tip: The 'description' command is used in interface configuration mode and does not affect interface functionality; it is purely for documentation.
CCNA exam tip: You may be asked to identify the command that adds a description to an interface; remember it is 'description' (not 'name' or 'label').
CCNA exam tip: Descriptions can be viewed with 'show interfaces' or 'show running-config interface [interface]'. The exam may test your ability to locate the description in output.
CCNA exam tip: Descriptions are often used in troubleshooting to quickly identify interface connections; a missing description might indicate incomplete documentation.
Common Mistakes
Mistake 1: Using 'name' instead of 'description' — the correct command is 'description', not 'name'.
Mistake 2: Forgetting to enter interface configuration mode before using the command — results in '% Invalid input detected' error.
Mistake 3: Including spaces or special characters that break the description — keep it alphanumeric with spaces and hyphens only.
description [text] vs show interfaces
These two commands both revolve around interface identity and health, but serve fundamentally different purposes: one sets administrative notes, the other retrieves operational statistics. They are often paired in troubleshooting workflows.
| Aspect | description [text] | show interfaces |
|---|---|---|
| Scope | Single interface configuration | All or specified interface statistics |
| Configuration mode | Interface Config | Privileged EXEC |
| Persistence | Written to running-config | Not saved, transient output |
| Effect on device | Adds descriptive text | Read-only, no change |
| Typical use | Documentation, asset tracking | Troubleshooting performance, errors |
Use description [text] when you need to label an interface for administrative purposes, such as indicating connected device or circuit ID.
Use show interfaces when you need to verify operational status, analyze traffic statistics, or diagnose physical or data-link layer issues.
Platform Notes
In IOS-XE (e.g., Catalyst 9000 series), the 'description' command syntax and behavior are identical to classic IOS. The output of 'show interfaces description' may include additional fields like 'Type' in newer versions, but the core functionality remains the same. In NX-OS (e.g., Nexus switches), the equivalent command is also 'description' under interface configuration mode, with the same syntax.
However, NX-OS supports a longer maximum length (up to 80 characters by default, configurable via 'description line-length' command). Additionally, NX-OS has a 'description' command for VLAN interfaces and port-channels. On ASA firewalls, the 'description' command is available under interface configuration mode and works identically, though ASAs often use 'nameif' for interface naming.
In IOS-XR (e.g., ASR 9000), the command is 'description' as well, but the maximum length is 256 characters. There are no significant differences between IOS versions 12.x, 15.x, and 16.x; the command has remained consistent. One nuance: in some older IOS versions, the description was limited to 80 characters, but modern versions support 240.
Always check the specific platform documentation for character limits. Overall, the 'description' command is universally supported across Cisco platforms with minimal variation, making it a reliable tool for multi-vendor environments.
Related Commands
show interfaces
Displays detailed Layer 1 and Layer 2 statistics for all interfaces or a specific interface: line protocol state, hardware type, MAC address, MTU, bandwidth, duplex, speed, input/output rates, error counters, and queue statistics.
show running-config
Displays the current active configuration in DRAM, showing all non-default settings.
Practice for the CCNA 200-301
Test your knowledge with practice questions covering all CCNA 200-301 exam domains.
Practice CCNA 200-301 Questions