Session Sharing

Overview

Session Sharing enables real-time collaborative terminal viewing in NetStacks. When you share a session, other team members can watch your terminal output live through a WebSocket connection. This is ideal for pair troubleshooting, training, change review, and NOC shift handoffs where multiple engineers need eyes on the same session simultaneously.

Key Capabilities

• Real-time streaming -- terminal output is broadcast to viewers over WebSocket with minimal latency
• Read-only viewer mode -- viewers observe the session without the ability to send input, ensuring the session owner retains full control
• Configurable expiration -- share tokens expire after a configurable duration, automatically revoking access
• Full audit trail -- every share event, viewer join, and viewer disconnect is logged with timestamps and user IDs
• Cross-instance routing -- in HA deployments, the connection broker routes viewer connections to the correct Controller instance hosting the session

Use Cases

• Pair troubleshooting -- share a live session with a senior engineer so they can observe your commands and provide guidance in real time
• Training and mentoring -- instructors can share their terminal while demonstrating procedures, allowing trainees to follow along live
• Change review -- share a maintenance window session with a change approver so they can verify each step as it happens
• NOC handoffs -- during shift changes, the outgoing engineer can share an active troubleshooting session with the incoming engineer for a seamless handoff

Session States

How It Works

Session sharing uses a WebSocket pub/sub architecture to stream terminal output from the session owner to one or more viewers in real time. The system is designed to work seamlessly across multiple Controller instances in high-availability deployments.

Sharing Pipeline

1. Share token generation — when you initiate a share, the Controller generates a unique share token with a configurable expiration time. This token serves as both the access credential and the WebSocket channel identifier.
2. WebSocket pub/sub — the sharer's terminal output is published to a WebSocket channel identified by the share token. Viewers subscribe to this channel by connecting with the token, receiving terminal output frames in real time.
3. Cross-instance routing — in HA deployments with multiple Controller instances, the connection broker routes viewer WebSocket connections to the correct Controller instance that is hosting the active session. This is transparent to viewers — they connect to any Controller instance and are automatically routed.
4. Audit trail logging — every share event is recorded in the audit system. This includes share creation (who shared, when, expiration), viewer joins (who connected, when, from where), and viewer disconnects (duration of viewing).
5. Shared tab styling — when a session is being shared, the session tab displays a visual indicator (distinct styling) so the owner always knows that their session is being observed by others.

Connection Architecture

Security Model

Share tokens are cryptographically generated and scoped to a single session. They cannot be reused after expiration or revocation. Viewers are authenticated through the standard NetStacks authentication flow before they can connect to a shared session. The share token alone is not sufficient — viewers must also have a valid NetStacks session and appropriate permissions.

Step-by-Step Guide

Workflow 1: Share a Session

1. Connect to a device and open a terminal session
2. Right-click the session tab and select Share Session
3. Configure the share expiration time (e.g., 30 minutes, 1 hour, 4 hours, or custom duration)
4. Click Create Share Link — a unique share URL is generated and copied to your clipboard
5. Send the share link to your team members via chat, email, or any communication channel
6. The session tab displays a visual indicator showing the session is being shared, along with a viewer count badge

Workflow 2: Join a Shared Session

1. Open the share link in your browser or paste it into the NetStacks application
2. Authenticate with your NetStacks credentials if not already logged in
3. The shared session opens in a read-only viewer mode — you can see all terminal output but cannot send any input
4. The viewer interface displays a banner indicating you are viewing a shared session along with the session owner's identity
5. The session owner sees your name appear in the viewer count on their session tab

Workflow 3: Manage Active Shares

1. Open the Session menu and select Manage Shares
2. View a list of all your currently active shared sessions with details including viewer count, time remaining, and share creation time
3. Click the viewer count to see individual viewer names and their connection times
4. Click Revoke next to any share to immediately disconnect all viewers and invalidate the share token
5. Expired shares are automatically cleaned up but remain visible in the audit log for compliance purposes

Code Examples

Create a Share Token

Generate a share token for an active session with a configurable expiration:

# Share a session with a 1-hour expiration
curl -X POST https://controller.example.com/api/v1/sessions/sess_abc123/share \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_in": "1h",
    "max_viewers": 10,
    "require_auth": true
  }'

# Response
{
  "share_id": "share_9f8e7d6c",
  "token": "ns_share_a1b2c3d4e5f6...",
  "share_url": "https://controller.example.com/shared/ns_share_a1b2c3d4e5f6",
  "websocket_url": "wss://controller.example.com/api/v1/sessions/shared/ns_share_a1b2c3d4e5f6/ws",
  "expires_at": "2026-03-25T15:30:00Z",
  "created_at": "2026-03-25T14:30:00Z",
  "created_by": "admin@example.com",
  "session_id": "sess_abc123",
  "state": "active"
}

Connect as a Viewer via WebSocket

Viewers connect to the shared session WebSocket endpoint to receive terminal output frames in real time:

# Connect to a shared session as a viewer
# The WebSocket endpoint streams terminal output frames
wscat -c "wss://controller.example.com/api/v1/sessions/shared/ns_share_a1b2c3d4e5f6/ws" \
  -H "Authorization: Bearer $VIEWER_TOKEN"

# Terminal output frames are received as JSON messages:
# {"type": "output", "data": "\u001b[32mrouter#\u001b[0m ", "timestamp": 1711374600123}
# {"type": "output", "data": "show ip bgp summary\r\n", "timestamp": 1711374601456}
# {"type": "resize", "cols": 120, "rows": 40, "timestamp": 1711374602000}
# {"type": "status", "message": "Session owner disconnected", "timestamp": 1711374700000}

List Active Shares for a Session

Retrieve all active and recent shares for a specific session:

# List all shares for a session
curl -s https://controller.example.com/api/v1/sessions/sess_abc123/shares \
  -H "Authorization: Bearer $TOKEN" | jq '.'

# Response
{
  "shares": [
    {
      "share_id": "share_9f8e7d6c",
      "state": "active",
      "created_at": "2026-03-25T14:30:00Z",
      "expires_at": "2026-03-25T15:30:00Z",
      "created_by": "admin@example.com",
      "viewer_count": 3,
      "viewers": [
        {
          "user_id": "usr_001",
          "email": "engineer1@example.com",
          "connected_at": "2026-03-25T14:32:15Z"
        },
        {
          "user_id": "usr_002",
          "email": "engineer2@example.com",
          "connected_at": "2026-03-25T14:35:42Z"
        },
        {
          "user_id": "usr_003",
          "email": "noc-lead@example.com",
          "connected_at": "2026-03-25T14:40:08Z"
        }
      ]
    },
    {
      "share_id": "share_1a2b3c4d",
      "state": "expired",
      "created_at": "2026-03-25T12:00:00Z",
      "expires_at": "2026-03-25T13:00:00Z",
      "created_by": "admin@example.com",
      "viewer_count": 0,
      "viewers": []
    }
  ]
}

Revoke a Share

Immediately revoke a share token and disconnect all viewers:

# Revoke a specific share — disconnects all viewers immediately
curl -X DELETE https://controller.example.com/api/v1/sessions/sess_abc123/shares/share_9f8e7d6c \
  -H "Authorization: Bearer $TOKEN"

# Response
{
  "share_id": "share_9f8e7d6c",
  "state": "revoked",
  "revoked_at": "2026-03-25T14:45:00Z",
  "revoked_by": "admin@example.com",
  "viewers_disconnected": 3
}

Q&A

Q: Can viewers send input to the shared session?

A: No. Viewers are strictly read-only. Only the session owner can type commands and interact with the terminal. This ensures that sharing a session does not introduce any risk of unauthorized command execution.

Q: How many viewers can join a shared session?

A: There is no hard limit on the number of viewers. Each viewer establishes an independent WebSocket connection to the Controller. You can optionally set a max_viewers limit when creating the share token to restrict the number of concurrent viewers.

Q: What happens when the session owner disconnects?

A: Viewers see a "Session owner disconnected" status message in their viewer interface. The share token remains valid until its configured expiration time. If the session owner reconnects and the token has not expired, viewers can continue observing the session.

Q: Is there an audit trail for shared sessions?

A: Yes. Every share creation, viewer join, and viewer disconnect event is logged in the audit system with timestamps, user IDs, and connection metadata. Administrators can query the audit log to see who shared what, who viewed it, and for how long.

Q: Does session sharing work across HA instances?

A: Yes. The connection broker automatically routes viewer WebSocket connections to the correct Controller instance that is hosting the active session. Viewers connect to any Controller instance and are transparently routed. This requires Valkey to be running and all Controller instances to be registered with the broker.

Q: Can I share a session with someone outside my organization?

A: By default, viewers must authenticate with valid NetStacks credentials. Sharing with external users requires those users to have guest accounts provisioned in your NetStacks instance. The require_auth flag cannot be disabled for security reasons.

Q: How do I know when someone is watching my session?

A: Shared sessions display a visual indicator on the session tab with a distinct styling. A viewer count badge shows how many people are currently connected. You can click the badge to see individual viewer names and their connection times.

Troubleshooting

Share Link Not Working

• Check that the share token has not expired — tokens have a configurable expiration and become invalid after the set duration
• Verify the share has not been manually revoked by the session owner using the Manage Shares interface
• Confirm the Controller is reachable from the viewer's network — the share URL must resolve to an accessible Controller instance
• Ensure the viewer has a valid NetStacks account and is authenticated

Viewers Cannot Connect

• Check WebSocket connectivity — some firewalls and proxies block WebSocket upgrade requests. Ensure the network path supports WSS connections to the Controller
• Verify firewall rules allow WebSocket (HTTP Upgrade) traffic on the Controller's port
• If using a reverse proxy (nginx, HAProxy), confirm it is configured to proxy WebSocket connections with appropriate timeout settings
• Check the Controller health endpoint to ensure the instance hosting the session is operational

Cross-Instance Routing Issues

• Verify that Valkey is running and accessible from all Controller instances — the connection broker depends on Valkey pub/sub for cross-instance routing
• Check connection broker logs on each Controller instance for routing errors or failed instance lookups
• Ensure all Controller instances are registered with the broker — unregistered instances cannot receive routed viewer connections
• If Valkey was recently restarted, Controller instances may need to re-register. Check instance registration status in the admin dashboard

Session Tab Not Showing Shared Indicator

• Verify the share was created successfully by checking the Manage Shares interface or the API response
• The visual indicator updates in real time — if it does not appear, try refreshing the session tab or reconnecting to the Controller
• Check the browser console for WebSocket connection errors that may prevent the UI from receiving share status updates

Related Features

• Terminal Overview — understand the terminal interface where session sharing originates
• Audit Logs — shared session events are recorded in the audit system for compliance reporting, including viewer identities and connection durations
• HA Deployment — configure the connection broker and Valkey for cross-instance session sharing in high-availability deployments
• Session Recording — record sessions for playback later, complementing the real-time viewing that session sharing provides
• Session Context — attach metadata and context to sessions that carries over to shared views