Config Mode Lock Mechanisms

This chapter describes how administrative lock mechanisms operate within StarOS configuration mode.

It contains the following sections:

Overview of Config Mode Locking

You enter the Global Configuration (config) mode via the Exec mode configure command. By default all administrative users share config mode. Multiple administrative users can share access to config mode simultaneously. This is called a shared-lock.

The primary indication for the existence of a shared-lock is a message displayed when entering config mode. 

Warning: One or more other administrators may be configuring this system

Note

There are no default restrictive behavior changes when entering config mode under a shared-lock.

When multiple administrators edit or save the running config, concurrent changes may result in conflicting, inconsistent, or missing configuration commands. A similar problem can occur when saving the configuration if someone is attempting to restart the system.

An optional lock [ force | warn ] keyword for the configure command allows an administrator to request a mutually exclusive lock of the config mode to assure that no other user is simultaneously modifying the configuration. This is called an exclusive-lock. Once an exclusive-lock is granted to an administrator, no one else can access config mode for the duration of the session while the lock is held. The exclusive-lock is terminated only when the user holding the lock exits to Exec mode.

A shutdown-lock is enabled during a save configuration operation to prevent other users from reloading or shutting down the system while the configuration is being saved.

Config mode locking mechanisms such as shared-lock, exclusive-lock and shutdown-lock mitigate the possibility of conflicting commands, file corruption and reboot issues.

Requesting an Exclusive-Lock

Important:

To avoid complications resulting from the failure of an administrator holding an exclusive lock to exit config mode, it is a best practice to configure all administrator accounts with CLI session absolute timeouts and/or idle timeouts. For additional information on setting these timeouts, see the Using the CLI for Initial Configuration section of the Getting Started chapter in this guide.

You can request an exclusive-lock on config mode by executing the Exec mode configure lock command. 

[local]host_name# configure [ <url> ] lock [ force | warn ]

If you specify a URL, the exclusive lock is associated with the pre-loaded configuration file. If you do not specify a URL, the exclusive lock is granted for the running configuration. For additional information see Effect of Config Lock on URL Scripts.

The force option forces all other administrators to exit out of configuration mode, including anyone currently holding the exclusive-lock.

The warn option warns all other administrators to exit out of configuration mode. This administrator will be taking the exclusive-lock soon. You may want to use this option before actually forcing administrators out of configuration mode,

If there are no other administrators in config mode, entering configure lock immediately grants you an exclusive-lock. 

[local]host_name# configure lock
Info: No one else can access config mode while you have the exclusive lock
[local]host_name#

When the exclusive lock is granted, no other administrators are allowed to enter into config mode or load a config file. Any other administrators attempting to enter into config mode or load a config file will see the following message: 

Failure: User <username> has the exclusive lock
 - please enter 'show administrators' for more information

If another administrator attempts to enter config mode with the exclusive-lock when it is already enabled, the following message appears: 

Failure: Another administrator is still in configuration mode
 - please enter 'show administrators' for more information

If you do not obtain an exclusive lock initially, you can use configure lock force.

If configure lock force is successful, all users who have been forced to exit to Exec mode will see a warning message indicating that they were forced to exit from config mode: 

[local]host_name(config)#
 Warning: Administrator <username> has forced you to exit from configuration mode
[local]host_name#

A configure lock force command may not be successful because there is a very small chance that another administrator may be in the middle of entering a password or performing a critical system operation that cannot be interrupted. In this case a failure message will appear: 

[local]host_name# configure lock force
 Failure: Another administrator could not release the configuration mode lock
 - please enter 'show administrators' for more information

The configure lock warn command sends a warning message to all config mode users (if any) and then waits up to 10 seconds to try and acquire the exclusive-lock. If any users are still in config mode, the config mode remains in a shared-lock state. 

[local]host_name# configure lock warn
 please wait for this message to be sent to the other administrators......
 [local]host_name(config)#

The other administrators would eventually see this message in their session output: 

[local]host_name(config)#
 Administrator <username> requires exclusive access to configuration mode
 >>> You need to exit from configuration mode as soon as possible <<<
 [local]host_name#

The configure lock warn command does not usually result in the exclusive-lock being acquired since the other administrators would typically not anticipate seeing the message in their session output.

Important:

StarOS logs all major config mode lock interactions to the event log and syslog facility (if configured). You can access a record of what interactions transpired at any time.

Effect of Config Lock on URL Scripts

When attempting to load a config script file using the configure <url> command, you must acquire either the shared-lock (default) or the exclusive-lock. Since the config script file typically contains the config command, the lock is actually held before and after the config command is parsed and executed.

The lock is held throughout the execution of the entire config file. Since the same shared-lock is used as the interactive config mode lock, a warning message is displayed followed by a confirmation prompt (if -noconfirm is not enabled) as shown in the example below. 

 [local]host_name# config /flash/myconfig.cfg
 Warning: One or more other administrators may be configuring this system
 Are you sure? [Y/N]:

With -noconfirm enabled, since all the commands are also echoed to the screen, the warning message will likely scroll off the screen and may not be noticed.

Important:

When StarOS first starts up, the Initial Boot Config File is always exclusively locked while loading.

Saving a Configuration File

Saving a partial or incomplete configuration file can cause StarOS to become unstable when the saved configuration is loaded at a later time. StarOS inhibits the user from saving a configuration which is in the process of being modified.

With a shared-lock in-effect for the duration of the save operation, you are prompted to confirm the save operation. 

[local]host_name# save configuration /flash/config.cfg
 Warning: One or more other administrators may be configuring this system
 Are you sure? [Y/N]:

If an exclusive-lock is being held by a user, the save operation will fail. 

[local]host_name# save configuration /flash/config.cfg
Failure: Configuration mode is currently locked, use ignore-lock to ignore lock

You can use the ignore-locks keyword with the save configuration command to override an existing exclusive-lock. 

[local]host_name# save configuration /flash/config.cfg ignore-locks
 Warning: Ignoring the configuration mode lock held by another administrator
Important:

The save configuration command also enables a shutdown-lock that prevents any other users from reloading or shutting down the system while the configuration is being saved. For additional information, refer to Reload and Shutdown Commands.

Reload and Shutdown Commands

The Exec mode reload and shutdown commands can result in a corrupted or partial configuration file when either of these commands are executed while a save configuration command is still in progress.

To prevent this problem from occurring, the reload and shutdown commands share a CLI shutdown-lock with all save configuration commands executed across StarOS. This means while any save configuration command is executing, StarOS cannot execute a reload or shutdown command. These commands are queued indefinitely until all save configuration operations are complete.

To prevent the user from being “hung” indefinitely in the wait queue, the user may press Control+C to exit the wait as shown in the example below. 

[local]host_name# reload
Are you sure? [Yes|No]: yes
Waiting for other administrators to finish saving configuration
(ctrl-c to abort) .......^C 
Action aborted by ctrl-c
[local]host_name#

On those rare occasions when you must reboot StarOS immediately regardless of the risk of corrupting any file(s) in the process of being saved, you can use the ignore-locks keyword in combination with the reload or shutdown command. With this option StarOS displays the appropriate warning message, but does not wait for save configuration operations to complete before initiating the reboot. 

[local]host_name# reload ignore-locks -noconfirm
Warning: One or more other administrators are saving configuration
Starting software 21.0...
Broadcast message from root (pts/2) Wed May 11 16:08:16 2016...
The system is going down for reboot NOW !!

Caution

Employing the ignore-locks keyword when rebooting the system may corrupt the configuration file.

show administrators Command

The Exec mode show administrators command has a single-character "M" column that indicates the current lock mode for the administrator’s session. The M-mode characters are defined as follows:

  • [blank] –  Administrator is in Exec mode

  • c – Administrator session is currently in Config Mode (shared-lock)

  • s – Administrator session is currently saving the config

  • f – Administrator session is currently loading the config file

  • L – Administrator session is currently in Config Mode with the exclusive-lock

The following is sample output of the show administrators command indicating current lock mode: 

[local]asr5500# show administrators
Administrator/Operator Name    M Type    TTY            Start Time
------------------------------ - ------- -------------- ------------------------
Bob                              admin   /dev/pts/2     Tue Mar 29 11:51:15 2016
Alice                          c admin   /dev/pts/1     Mon Mar 28 14:41:15 2016
Carol                            admin   /dev/pts/0     Mon Mar 28 14:40:52 2016