Configuration Sessions: Parallel Work Without Conflicts

November 25, 2025 · 6 min read

Two engineers SSH into the same router. Both type configure. Both make changes. Both commit. One overwrites the other’s work. Nobody knows what happened until something breaks.

VyOS configuration sessions solve this. Each session is isolated. Changes don’t interfere. Conflicts are detected before commit, not after outage.

Sessions prevent “who changed what” mysteries before they become incidents.

The Problem

Without sessions, configuration mode is a shared space:

Engineer A                    Engineer B
-----------                   -----------
configure                     configure
set firewall rule 10...      set interfaces eth1...
                              commit  ← B's changes saved
commit  ← A overwrites B's changes!

Engineer B’s changes are silently lost. No warning, no merge, just gone.

How Sessions Work

VyOS 1.4+ supports configuration sessions. Each session:

Has unique ID
Isolated working copy of config
Can see other sessions
Detects conflicts on commit

Engineer A (session abc123)    Engineer B (session def456)
--------------------------     --------------------------
configure                      configure
# Working on isolated copy     # Working on isolated copy
set firewall...                set interfaces...
# Changes only in abc123       # Changes only in def456

Session Management

View Active Sessions

# List all configuration sessions
show configuration sessions

# Example output:
# Session ID          User        Started
# abc123             admin        2025-01-08 10:15:03
# def456             engineer     2025-01-08 10:18:22

Enter Named Session

# Create or resume named session
configure session my-firewall-changes

# Session persists even if you disconnect
# SSH back in, resume:
configure session my-firewall-changes

# All your uncommitted changes are still there

Discard Session

# Exit and discard changes
exit discard

# Or explicitly delete session
delete configuration session my-firewall-changes

Conflict Detection

What Happens on Conflict

# Engineer A in session abc123:
configure
set interfaces ethernet eth0 description "WAN Link"
commit  # Success

# Engineer B in session def456:
configure
set interfaces ethernet eth0 description "Internet Uplink"
commit  # ERROR: Configuration conflict detected

# Output:
# The following configuration conflicts were detected:
# interfaces ethernet eth0 description
#   Current: "WAN Link"
#   Your change: "Internet Uplink"

Resolving Conflicts

# Option 1: Refresh and redo
exit discard
configure
# See current config
show interfaces ethernet eth0
# Make decision, apply change
set interfaces ethernet eth0 description "Internet Uplink"
commit

# Option 2: Force your version
commit --force  # Overwrites conflicting values
# Use with caution - you're overwriting someone's work

# Option 3: Merge manually
compare  # See differences
# Adjust your changes to accommodate both

Session Workflow Examples

Example 1: Large Firewall Update

# Start named session for tracking
configure session firewall-2025-01-08

# Make many changes over time
set firewall ipv4 name WAN-IN rule 100 ...
set firewall ipv4 name WAN-IN rule 101 ...
set firewall ipv4 name WAN-IN rule 102 ...

# Save session, exit for lunch
exit

# Come back, continue work
configure session firewall-2025-01-08
set firewall ipv4 name WAN-IN rule 103 ...

# Review all changes
show | compare

# Commit when ready
commit-confirm 5
confirm

# Session automatically cleaned up after commit

Example 2: Team Coordination

# Engineer A: Working on BGP
configure session bgp-changes
set protocols bgp neighbor 10.0.0.1 ...

# Engineer B: Working on firewall (different session)
configure session firewall-changes
set firewall ipv4 name ...

# Both can work simultaneously
# Both can commit (no conflicts - different config sections)

Example 3: Testing Before Commit

# Create test session
configure session testing-nat

# Make changes
set nat source rule 100 ...

# Compare what would change
show | compare

# Show the commands that would be applied
show | commands

# Decide to discard
exit discard
# Or decide to apply
commit

Viewing Session Differences

Compare Session to Running Config

configure session my-changes

# What would change if I commit?
show | compare

# Output shows:
# +set interfaces ethernet eth0 description "New description"
# -set interfaces ethernet eth0 description "Old description"

Compare Sessions to Each Other

# Not directly supported, but you can:

# From session A, save diff
show | compare > /tmp/session-a-diff.txt

# From session B, save diff
show | compare > /tmp/session-b-diff.txt

# Compare files
diff /tmp/session-a-diff.txt /tmp/session-b-diff.txt

Session Timeout

Sessions don’t persist forever:

# Default: sessions expire after 30 minutes of inactivity

# Check current timeout
show configuration session-timeout

# Modify timeout (in minutes)
configure
set system session-timeout 60
commit

Persistent Sessions

For long-running work:

# Keep session alive with periodic activity
# Or increase timeout significantly

# Check session status
show configuration sessions

Best Practices

1. Use Named Sessions for Major Changes

# Bad: Anonymous session
configure  # What was I working on?

# Good: Descriptive name
configure session ticket-12345-add-bgp-peer

2. One Logical Change Per Session

# Bad: Everything in one session
configure session all-my-stuff
set firewall ...
set bgp ...
set nat ...
# Huge commit, hard to rollback one thing

# Good: Separate sessions
configure session firewall-update
# ... only firewall changes

configure session bgp-peer-addition
# ... only BGP changes

3. Review Before Commit

configure session important-change

# Always review what you're committing
show | compare
show | commands

# Then commit
commit-confirm 5

4. Clean Up Abandoned Sessions

# List old sessions
show configuration sessions

# Delete abandoned ones
delete configuration session old-test-session
delete configuration session johns-forgotten-work

Limitations

What Sessions Don’t Do

Don’t provide history - Sessions are temporary workspaces, not audit trails
Don’t allow collaborative editing - One user per session
Don’t auto-merge - Conflicts must be resolved manually
Don’t persist across reboots - Uncommitted sessions are lost

When Sessions Aren’t Enough

For complex team workflows, consider:

Git-based configuration management
Ansible/Terraform for deployments
Separate staging environment

Sessions handle concurrent edits. Version control handles history and rollback.

Troubleshooting

Can’t Enter Configuration Mode

# Another session might be locked
show configuration sessions

# If stuck session exists
# Try to take ownership (if you're sure)
configure session stuck-session
exit discard

Lost Session Changes

# Session timed out or router rebooted?
# Uncommitted changes are gone

# Always commit before:
# - Long breaks
# - Router maintenance
# - End of work day

Conflict on Every Commit

# Another process might be modifying config

# Check for automation
show log | grep -i commit

# Coordinate with team
# Pause automated deployments during manual work

The Lesson

Sessions prevent “who changed what” mysteries before they become incidents.

On a shared router:

Without sessions: Chaos, overwrites, mystery changes
With sessions: Isolation, conflict detection, clear ownership

The few seconds to type configure session descriptive-name saves hours of debugging “why did this config disappear?”

Every team environment should use sessions. Every major change should use a named session. Every commit should follow a review.

The router knows when you’re about to overwrite someone’s work. Let it tell you.