BGP Configuration Guide for Cisco 8000 Series Routers, Cisco IOS XR Releases

PDF

BGP graceful maintenance

Updated: February 28, 2026

Want to summarize with AI?

Log in

Overview

Guides BGP graceful maintenance practices by addressing restrictions, operational principles, key recommendations, and best practices, and supplies procedures for activation, route preference adjustments, GSHUT policy configuration, verification, and managing CLUSTER_LIST attributes with associated workflows.

BGP graceful maintenance is a routing feature that

  • allows routers or links to remain in service while the network reroutes traffic to alternative paths,

  • minimizes traffic loss during convergence by enabling the network to find alternate routes before taking a router or link out of service, and

  • supports both shutdown and startup scenarios to reduce traffic disruption.

This feature is especially useful in networks with long convergence times caused by factors such as large routing tables or route reflectors.

Restrictions for BGP graceful maintenance

These restrictions apply to BGP graceful maintenance:

  • Routers configured to send the GSHUT community attribute require other routers to interpret it via matching routing policies and setting lower preferences.

  • The LOCAL_PREF attribute is not sent to another AS, so it cannot be used on eBGP links, except between member-ASs of an AS confederation.

  • Alternate routes must exist in the network; otherwise, advertising a lower preference has no effect (e.g., singly-homed customer routers without alternate routes).

Graceful maintenance operation

When you activate BGP Graceful Maintenance, you ensure a controlled traffic shift by signaling reduced route preference to neighboring routers, prompting them to select alternative paths.

  • Signaling Reduced Preference: You can signal reduced route preference using these methods:

    • Add GSHUT community: This method allows remote routers the flexibility to define their own preference based on a policy match.

    • Reduce LOCAL_PREF value: This method is effective for internal BGP neighbors, especially if remote routers do not process the GSHUT community.

    • Prepend AS Path: This method works for both internal and external BGP neighbors, particularly when remote routers do not recognize the GSHUT community.

  • Impact on BGP Connections: When you activate Graceful Maintenance on a BGP connection, two key operations occur:

    • Re-advertisement of received routes: All routes received from the connection are re-advertised to other neighbors with a lower preference. This applies only to routes that were originally advertised to those neighbors.

    • Re-advertisement of advertised routes: All routes previously advertised to the connection are re-advertised with a lower preference.

  • Internal Tagging for Received Routes: To facilitate the re-advertisement of received routes, we internally tag them with a graceful-shut attribute. This attribute is local to the router and is not advertised via BGP. You can view this attribute using the show bgp command. This differs from the GSHUT community, which is advertised by BGP.

  • Route Selection Preference: All routes possessing the graceful-shut attribute receive the lowest preference during route selection. Any new route updates exchanged on a BGP session under Graceful Maintenance are processed with this same preference adjustment.

Guidelines for inter-autonomous system usage

Advertise a lower preference to another autonomous system (AS) in the public Internet only when necessary. Unnecessary advertisement may cause excessive routing updates in remote networks, which can be undesirable.

Key points:

  • Avoid advertising lower preference unless required to prevent unnecessary routing advertisements.

  • Configure the router with the send-community-gshut-ebgp setting under the neighbor address family to originate the GSHUT community to the eBGP neighbor.

  • Be aware that this setting affects only the GSHUT community you add; it does not alter the GSHUT community on routes you receive.

Best practices for handling the graceful-shut attribute in BGP

  • Assign the lowest preference to any BGP route tagged with the graceful-shut attribute during route selection to maintain correct routing behavior.

  • Remember that the graceful-shut attribute is internal and is not advertised to external BGP peers.

  • Do not confuse the graceful-shut attribute with the GSHUT community, which is advertised externally by BGP.

  • During Graceful Maintenance, treat any new route updates received or sent on a BGP session in the same way.

This approach ensures proper route handling and avoids inadvertent routing preferences during network maintenance.

Requirement: Verify network convergence before performing a graceful maintenance shutdown

Always confirm full network convergence before shutting down a router or link after activating graceful maintenance. This step is essential to prevent traffic loss and service disruption.

Premature shutdown before convergence can cause severe operational hazards and substantial traffic loss. Network-wide convergence may take seconds to over an hour and cannot be determined solely by the local router state.

By verifying convergence, you minimize the risk of traffic blackholing and ensure a smooth, uninterrupted transition during maintenance.

Apply these instructions every time you perform graceful maintenance and intend to shut down a router or link. Skipping this step can lead to critical service impacts.

To determine full convergence:

  • Monitor BGP messaging queues and traffic flow.

  • Use the show bgp <vrf> <afi> <safi> summary commands to confirm both InQ and OutQ are zero) for all neighbors.

  • Ensure traffic is no longer sent to the router being maintained.

Configure graceful maintenance on a BGP router for all neighbors

Advertise routes with the GSHUT community to enable graceful service maintenance across all BGP neighbors through a single configuration.

Before you begin

  • Verify you have the required access permissions and credentials to configure the BGP router.

  • Confirm that the router is operational and that BGP sessions with neighbors are established.

Procedure

Enter BGP router configuration mode and configure graceful maintenance for all neighbors.

Example:

Router# configure
Router(config)# router bgp 120
Router(config-bgp)# graceful-maintenance activate all-neighbors

What to do next

  • After activating Graceful Maintenance, wait for all routes to be sent and for neighboring routers to redirect traffic away from the router or link under maintenance. Once traffic is redirected, it is safe to take the router or link out of service.

  • To monitor progress, use the show bgp summary command and check the OutQ value for neighbors. When OutQ reaches 0, no more updates remain to be sent.

Configure graceful maintenance on a neighbor

Enable the router to announce routes with graceful maintenance attributes, including the GSHUT community, to a neighbor.

Before you begin

Verify the IP address of the BGP neighbor is known and reachable.

Procedure

Enable graceful maintenance on BGP neighbor.

Example:


Router# configure
Router(config)# router bgp 120
Router(config-bgp)# neighbor 172.168.40.24
Router(config-bgp-nbrgrp)# graceful-maintenance activate
Router(config-bgp)# commit

Activating graceful maintenance on a single neighbor enables coordinated route advertisement with GSHUT community attributes for the specific neighbor in the group, facilitating efficient maintenance operations.

Graceful maintenance is activated for the specified neighbor, enabling coordinated route advertisement with the GSHUT community attribute for maintenance operations.

Configure the router to reduce route preference for graceful maintenance

Allow alternate BGP routes to take over before removing a link or router by lowering route preference.

Use this procedure to safely enable BGP graceful maintenance without routing disruption. Lowering the route preference (local-preference) ensures traffic shifts to alternative paths while maintaining service continuity.

Before you begin

  • Ensure alternate network paths are available to receive redirected traffic.

  • Prepare the route policy that matches the GSHUT community to set the lower local preference value.

Follow the steps to reduce the route preference on the router :

Procedure

1.

Configure the BGP neighbor for graceful maintenance with a lower local preference:

Example:

Router# configure
Router(config)# router bgp 120
Router(config-bgp)# neighbor 172.168.40.24
Router(config-bgp-nbr)# remote-as 2002
Router(config-bgp-nbr)# graceful-maintenance local-preference 4
2.

Define a route policy that matches the GSHUT community and sets the local preference to 0:

Example:

Router(config)# route-policy gshut
Router(config-rpl)# if community matches-any gshut then
Router(config-rpl)# set local-preference 0
Router(config-rpl)# endif
Router(config-rpl)# pass
Router(config-rpl)# end-policy
3.

Apply the route policy inbound on the configured BGP neighbor:

Example:

Router# configure
Router(config)# router bgp 120
Router(config-bgp)# neighbor 172.168.40.24
Router(config-bgp-nbr)# address-family ipv4 unicast
Router(config-bgp-nbr-af)# route-policy gshut in

  • Attributes for graceful maintenance are added to a route update message after applying an outbound policy.

  • Routes received from a GSHUT neighbor are marked with a GSHUT attribute to distinguish them from routes received with the GSHUT community.

  • When a neighbor exits maintenance, its GSHUT attribute is removed, but the community tag remains.

  • The GSHUT attribute is internal and used only for path selection; it is not sent in BGP messages.

The router advertises routes with lower preference, allowing alternate routes to be selected for traffic before you take down a link or the router.

Configure BGP inbound route policy for GSHUT community

Configure route policy for graceful maintenance by lowering the preference for GSHUT community.

This configuration defines and applies a BGP route policy that sets the local-preference to 0 for incoming routes carrying the gshut BGP community.

Before you begin

Ensure alternate paths exist: The graceful maintenance feature relies on traffic having other routes to take; without them, this configuration is ineffective.

Ensure you have a backup of the current configuration: Always save a copy of your router's configuration before making any changes to allow for easy rollback if needed.

Follow these steps to configure a BGP inbound route policy that lowers the preference of routes carrying the GSHUT community, and facilitating graceful service maintenance.

Procedure

Configure route policy matching GSHUT community to lower route preference.

Example:

Router(config)# route-policy gshut
Router(config-rpl)# if community matches-any gshut then
Router(config-rpl-if)# set local-preference 0
Router(config-rpl-if)# endif
Router(config-rpl-if)# pass
Router(config-rpl-if)# end-policy
Router(config-rpl-if)# exit
Router(config-rpl)# exit
Router(config)# router bgp 120
Router(config-bgp)# neighbor 10.0.0.3
Router(config-bgp-nbr)# address-family ipv4 unicast
Router(config-bgp-nbr)# route-policy gshut in
Router(config-bgp-nbr)# exit
Router(config-bgp)# exit
Router(config)# exit

Verify BGP graceful maintenance activation and attributes

Ensure BGP graceful maintenance is active and correctly configured to allow for seamless routing transitions during planned maintenance.

Use this task to verify that your BGP routers are properly advertising the graceful-shutdown community and associated attributes, preventing network disruptions during maintenance events.

Before you begin

Ensure you have access to the router command.

Confirm you have privileges to run show commands.

Follow these steps to verify BGP graceful maintenance activation and attributes.

Procedure

1.

Verify BGP routes with graceful-shutdown community

Example:

Router# show bgp 192.0.2.1 
...
192.0.2.10 from 192.0.2.10 (198.51.100.1)
Received Label 24000
Origin incomplete, metric 0, localpref 100, valid, internal, best, group-best,
import-candidate
Received Path ID 0, Local Path ID 1, version 4
Community: graceful-shutdown
Originator: 198.51.100.1, Cluster list: 198.51.100.1

Review the output for entries showing the graceful-shutdown community and related path attributes.

These lines confirm that BGP graceful maintenance is active and that the route is marked accordingly to allow alternate paths to take over before a link or router is taken down:

  • Community: graceful-shutdown: This line explicitly shows that the route carries the graceful-shutdown community attribute.

  • Origin incomplete, metric 0, localpref 100, valid, internal, best, group-best, import-candidate: These status codes and attributes confirm the route's state, including the presence of the graceful-shut path attribute as part of the route's characteristics.

  • Received Path ID 0, Local Path ID 1, version 4: This line provides path identification details relevant to the graceful maintenance feature.
2.

Verify the graceful-shutdown community and path attribute.

Example:

Router# show bgp community graceful-shutdown
BGP router identifier 198.51.100.1, local AS number 4
BGP generic scan interval 60 secs
BGP table state: Active
Table ID: 0xe0000000 RD version: 18
BGP main routing table version 18
BGP scan interval 60 secs
Status codes: s suppressed, d damped, h history, * valid, > best
i - internal, r RIB-failure, S stale, N Nexthop-discard
Origin codes: i - IGP, e - EGP, ? - incomplete
Network Next Hop Metric LocPrf Weight Path
* 10.5.5.5/32 10.10.10.1 88 0 1 ?
Processed 1 prefixes, 1 paths

These lines collectively confirm that the graceful maintenance feature is active and that the routes are marked accordingly to allow alternate paths to take over before a link or router is taken down.

  • Community: graceful-shutdown: This line explicitly shows that the route carries the graceful-shutdown community attribute, indicating that graceful maintenance is active for this route.

  • Network Next Hop Metric LocPrf Weight Path and the following line: * 10.5.5.5/32 10.10.10.1 88 0 1 ?: This shows the network prefix and associated attributes, confirming the route is valid and active under graceful maintenance.

  • Processed 1 prefixes, 1 paths: This confirms the number of prefixes and paths processed with the graceful-shutdown community.
3.

Verify if graceful maintenance is locally active on a BGP neighbor and to view local preference and AS prepends:

Example:

Router# show bgp neighbor 192.0.2.1
...
Graceful Maintenance locally active, Local Pref=45, AS prepends=3
...
For Address Family: IPv4 Unicast
...
GSHUT Community attribute sent to this neighbor
...

These lines collectively confirm that graceful maintenance is active and that the relevant attributes are applied and communicated to the neighbor:

  • Graceful Maintenance locally active, Local Pref=45, AS prepends=3: This line confirms that graceful maintenance is currently active on the neighbor, showing the local preference value and the number of AS path prepends applied.

  • For Address Family: IPv4 Unicast: This indicates the address family context for which the graceful maintenance attributes apply.

  • GSHUT Community attribute sent to this neighbor: This line shows that the GSHUT community attribute is being sent to the neighbor, which is part of the graceful maintenance signaling.
4.

Verify the key attributes of the BGP neighbor that indicates that the graceful maintenance is enabled:

Example:

Router# show bgp neighbor 10.12.12.5 configuration

neighbor 10.12.12.5
remote-as 1 []
graceful-maintenance 1 []
gr-maint local-preference 45 []
gr-maint as-prepends 3 []
gr-maint activate []

These lines confirm that graceful maintenance is active and configured with the specified local preference and AS path prepends for this neighbour:

  • remote-as 1

  • gr-maint local-preference 45

  • gr-maint as-prepends 3

  • gr-maint activate
5.

List all community set objects and view graceful maintenance feature attributes:

Router# show rpl community-set
Listing for all Community Set objects
community-set gshut
graceful-shutdown
end-set

These lines display the community sets configured for graceful maintenance on the router.

6.

Monitor syslog warning for BGP graceful maintenance activation.

RP/0/0/CPU0:Jan 28 22:01:36.356 : bgp[1056]: %ROUTING-BGP-5-ADJCHANGE : neighbor 10.10.10.4 Up (VRF: default) (AS: 4)
WARNING: Graceful Maintenance is Active
Use this warning as a reminder to deactivate graceful maintenance after the BGP convergence completes.

How a CLUSTER_LIST attribute is used

The CLUSTER_LIST attribute propagation rules vary depending on the Cisco software release version, specifically whether the device runs software before or after the implementation of the BGP Multiple Cluster IDs (MCID) feature. This distinction also applies to loop prevention mechanisms based on the CLUSTER_LIST attribute.

Summary

The key components involved in the CLUSTER_LIST attribute propagation and loop prevention process are:

  • Route Reflector (RR): The device responsible for reflecting routes and managing the CLUSTER_LIST attribute during route propagation.

  • iBGP neighbors: These include both clients and nonclients connected to the RR, each potentially assigned a cluster ID.

  • CLUSTER_LIST attribute: A BGP attribute that tracks the cluster IDs a route has passed through to prevent routing loops.

  • Global cluster ID: A unique identifier assigned to the RR used in classic propagation and loop prevention.

  • Cluster IDs Assigned to Neighbors: Identifiers assigned to iBGP neighbors used in the MCID propagation and loop prevention process.

This process ensures that routes are properly propagated with updated CLUSTER_LIST attributes and that routing loops are prevented by discarding routes containing the RR’s global cluster ID or any cluster ID of its iBGP neighbors, depending on the software release version.

This process occurs dynamically during route reflection and route reception.

  • The network administrator identifies whether the device is running a Cisco software release before (Classic) or after (MCID) the implementation of the BGP Multiple Cluster IDs feature.

Workflow

These stages describe how the CLUSTER_LIST attribute propagation and loop prevention process works in BGP route reflection, differentiating between classic and MCID software releases.

  1. The device identifies whether it is running a classic release or an MCID release based on the implementation of the multiple cluster IDs feature. Route Reflector (RR)
    • The behavior differs between:
    When...

    and..

    		 Then...

    The device runs a classic release

    the route reflector (RR) prepares to reflect a route

    The RR appends its global cluster ID to the CLUSTER_LIST attribute.

    The device runs a classic release

    the received route has no CLUSTER_LIST attribute

    The RR creates a new CLUSTER_LIST attribute with its global cluster ID.

    The device runs an MCID release

    The route reflector (RR) prepares to reflect a route

    The RR appends the cluster ID of the neighbor from which the route was received to the CLUSTER_LIST attribute.

    The device runs an MCID release

    The received route has no CLUSTER_LIST attribute

    The RR creates a new CLUSTER_LIST attribute with the neighbor’s cluster ID.

    The device runs an MCID release

    The neighbor is a nonclient without an associated cluster ID

    The RR uses its global cluster ID for the CLUSTER_LIST attribute.

    The device runs a classic release

    The RR receives a route

    The RR discards the route if its global cluster ID is present in the route’s CLUSTER_LIST attribute.

    The device runs an MCID release

    The RR receives a route

    The RR discards the route if its global cluster ID or any cluster ID assigned to its iBGP neighbors is present in the CLUSTER_LIST attribute.

Configure a cluster ID per neighbor

Configure a unique cluster ID for each iBGP neighbor, typically a route reflector, to enhance loop-prevention and control client-to-client route reflection.

Assigning a cluster ID per neighbor modifies the BGP loop-prevention mechanism to consider multiple cluster IDs. It also enables disabling client-to-client route reflection based on cluster ID. When a cluster ID changes for a neighbor, BGP performs inbound and outbound soft refreshes for all iBGP peers automatically.

Before you begin

Ensure you have access to the router and the necessary privileges to configure BGP.

Follow these steps to configure a cluster ID per neighbor:

Procedure

1.

For each iBGP neighbor (typically a route reflector), assign a unique cluster ID in BGP configuration mode.

Example:

Router(config)# router bgp 65000
Router(config-router)# neighbor 192.168.1.2
Router(config-router)# remote-as 65000
Router(config-router)# cluster-id 0.0.0.1
2.

Verify cluster IDs with the show bgp process details command, ensuring all assigned cluster IDs appear in Active Cluster IDs

Example:

show bgp process details
BGP Process Information:
BGP is operating in STANDALONE mode
Autonomous System number format: ASPLAIN
Autonomous System: 65000
Router ID: 10.10.1.92 (manually configured)
Default Cluster ID: 10.10.1.92
Active Cluster IDs: 10.10.1.92, 10.10.3.93, 10.10.4.20
10.10.5.20, 198.51.100.254 ...

This output shows that the cluster ID is assigned per neighbor, modifying the loop-prevention mechanism to handle multiple cluster IDs and enabling control over client-to-client route reflection based on cluster ID. BGP automatically performs soft refreshes for all iBGP peers upon cluster ID changes.
3.

Verify the last committed configuration change.

Example:

show configuration commit change last 1

Building configuration... !!
 IOS XR Configuration 6.1.3 
  router bgp 65000
  neighbor 198.51.100.254	<<< not operational, no AFs etc 
  remote-as 65000 cluster-id 198.51.100.254 
 !
! 
end

The output verifies that the neighbor 198.51.100.254 is configured with a cluster ID but is currently not operational due to missing Address Family configurations. This confirms that cluster IDs are tracked and included in active cluster IDs regardless of neighbor operational state, consistent with BGP’s loop-prevention and route reflection mechanisms.

Configuring a unique cluster ID per iBGP neighbor modifies the BGP loop-prevention mechanism to handle multiple cluster IDs and enables precise control over client-to-client route reflection. This configuration triggers automatic inbound and outbound soft refreshes for all iBGP peers upon cluster ID changes, enhancing network stability and route reflection flexibility.

Disable client-to-client reflection for specified cluster IDs

Disable client-to-client reflection for specific BGP cluster IDs to control route reflection behavior.

When the software changes the reflection state for a given cluster ID, BGP sends an outbound soft refresh to all clients. This task is performed to disable client-to-client reflection for specified cluster IDs in a BGP configuration.

Before you begin

Ensure you have access to the router and appropriate privileges to configure BGP.

Follow these steps to disable client-to-client reflection for specified cluster IDs.

Procedure

1.

Disable client-to-client reflection for specified cluster IDs.

Example:

Router(config)# router bgp 65000
Router(config-bgp)# address-family ipv4 unicast
Router(config-bgp-af)# bgp client-to-client reflection cluster-id 0.0.0.1 disable
2.

Verify the configuration by displaying the BGP process information.

Example:

Router# show bgp process
BGP Process Information: 
BGP is operating in STANDALONE mode
Autonomous System number format: ASPLAIN
Autonomous System: 65000
Router ID: 0.0.0.0
Active Cluster IDs:  0.0.0.1
Fast external fallover enabled
Platform RLIMIT max: 2147483648 bytes
Maximum limit for BMP buffer size: 409 MB
Default value for BMP buffer size: 307 MB
Current limit for BMP buffer size: 307 MB
Current utilization of BMP buffer limit: 0 B
Neighbor logging is enabled
Enforce first AS enabled
Default local preference: 100
Default keepalive: 60
Non-stop routing is enabled
Update delay: 120
Generic scan interval: 60

Address family: IPv4 Unicast
Dampening is not enabled
Client reflection is not enabled in global config
Dynamic MED is Disabled
Dynamic MED interval : 10 minutes
Dynamic MED Timer : Not Running
Dynamic MED Periodic Timer : Not Running
Scan interval: 60
Total prefixes scanned: 0
Prefixes scanned per segment: 100000
Number of scan segments: 1
Nexthop resolution minimum prefix-length: 0 (not configured)
Main Table Version: 2
Table version synced to RIB: 2
Table version acked by RIB: 2
IGP notification: IGPs notified
RIB has converged: version 0
RIB table prefix-limit reached ?  [No], version 0
Permanent Network Unconfigured

Node                Process     Nbrs Estb Rst Upd-Rcvd Upd-Sent Nfn-Rcv Nfn-Snt
node0_0_CPU0        Speaker        1    0   2        0        0       0       3

Client-to-client reflection is disabled for the specified cluster ID, and BGP sends an outbound soft refresh to all clients to apply the change.