Bulk Operations

Overview

Bulk operations let you perform actions across multiple devices in a single operation instead of repeating the same action device by device. When you manage hundreds or thousands of network devices, the ability to capture configs from all core routers, update credentials across an entire site, or apply tags to all firewalls at once is essential for operational efficiency.

NetStacks supports bulk operations through multiple selection mechanisms:

• Manual selection — Select individual devices using checkboxes in the device list.
• Filter-based selection — Filter the device list by device type, site, or tag, then select all matching devices.
• Tag-based grouping — Apply tags to devices for logical grouping (e.g., production, core, dc-east) and select devices by tag.

Available Bulk Actions

How It Works

Device Selection

The device list in the Admin UI supports multi-select with checkboxes. You can select individual devices, use "Select All" to select the current page, or filter the list first and then select all matching results. The selection state is maintained as you navigate between pages.

Filter-Based Selection

The device list supports filters that narrow the displayed devices before selection:

• Device type — Show only devices of a specific platform (e.g., all cisco_ios devices).
• Site — Show only devices at a specific location (e.g., dc-east).
• Source — Filter by how the device was added (manual, csv_import, netbox).
• Tags — Show only devices with specific tags.

Tags and Organization

Tags are string labels attached to devices for flexible grouping. Unlike rigid folder hierarchies, tags allow a device to belong to multiple logical groups simultaneously. Common tagging strategies:

• By function — core, distribution, access, edge, firewall
• By environment — production, staging, lab, dr
• By site — dc-east, dc-west, branch-nyc, branch-lon
• By compliance — pci, hipaa, sox

Parallel Execution

Bulk config captures and connection tests run concurrently using a configurable concurrency limit. NetStacks uses a semaphore to control the number of simultaneous SSH connections, preventing network saturation. Each device operation runs independently — if one device fails, the remaining devices continue.

Metadata-Only Operations

Tag updates, credential changes, and delete operations are metadata-only — they modify the device record in PostgreSQL without establishing SSH connections. These operations complete instantly regardless of device count.

Step-by-Step Guide

Apply Tags to Devices for Grouping

1. Navigate to Devices in the Admin UI.
2. Filter the device list by site or device type to narrow your selection (e.g., filter by site=dc-east and device_type=cisco_ios).
3. Select the devices you want to tag using checkboxes.
4. Click Bulk Actions → Add Tags.
5. Enter one or more tags (e.g., production, core).
6. Click Apply. Tags are added to all selected devices without removing existing tags.

Bulk Capture Configs from Selected Devices

1. Filter the device list or select devices manually.
2. Click Bulk Actions → Capture Config.
3. NetStacks creates a snapshot collection and begins concurrent config capture from all selected devices.
4. Monitor progress in the Snapshots page. The snapshot shows total, successful, and failed device counts as collection progresses.

Bulk Update Credentials

1. Select the devices that need a credential change (e.g., all devices at a site where the SSH password was rotated).
2. Click Bulk Actions → Update Credential.
3. Select the new credential from the vault dropdown.
4. Click Apply. The default_credential_id is updated on all selected devices.
5. Optionally run Test Connection on the same selection to verify the new credential works.

Bulk Delete Devices

1. Select the devices to remove.
2. Click Bulk Actions → Delete.
3. Review the confirmation dialog showing how many devices will be deleted.
4. Type the confirmation phrase and click Delete.

Code Examples

List Devices Filtered by Type and Site

# Get all Cisco IOS devices at dc-east
curl -s "http://localhost:3000/api/devices?device_type=cisco_ios&site=dc-east" \
  -H "Authorization: Bearer ${TOKEN}" | jq '{
    total: .total,
    devices: [.devices[] | {name, host, device_type, site}]
  }'

# Response:
# {
#   "total": 14,
#   "devices": [
#     {"name": "core-rtr-01", "host": "10.1.0.1", "device_type": "cisco_ios", "site": "dc-east"},
#     {"name": "core-rtr-02", "host": "10.1.0.2", "device_type": "cisco_ios", "site": "dc-east"},
#     ...
#   ]
# }

Bulk Update Credential via API

# Get device IDs matching a filter, then update each device's credential
DEVICE_IDS=$(curl -s "http://localhost:3000/api/devices?site=dc-east" \
  -H "Authorization: Bearer ${TOKEN}" | jq -r '.devices[].id')

NEW_CRED_ID="b2c3d4e5-f6a7-8901-bcde-f12345678901"

for DEVICE_ID in ${DEVICE_IDS}; do
  curl -X PUT "http://localhost:3000/api/devices/${DEVICE_ID}" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Content-Type: application/json" \
    -d "{"default_credential_id": "${NEW_CRED_ID}"}"
  echo "Updated: ${DEVICE_ID}"
done

Snapshot All Core Routers

# Create a snapshot targeting all devices with device_type cisco_ios
curl -X POST http://localhost:3000/api/devices/snapshots \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Core Router Backup - 2026-03-10",
    "description": "Weekly backup of all Cisco IOS core routers",
    "snapshot_type": "manual",
    "device_filter": {
      "device_type": "cisco_ios"
    }
  }'

# Then trigger collection
SNAPSHOT_ID="<id from response>"
curl -X POST "http://localhost:3000/api/devices/snapshots/${SNAPSHOT_ID}/collect" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}'

Export Devices as CSV

# Export all devices to CSV format
curl -s http://localhost:3000/api/devices?limit=10000 \
  -H "Authorization: Bearer ${TOKEN}" | jq -r '
  ["name","host","port","device_type","manufacturer","model","site"],
  (.devices[] |
    [.name, .host, (.port|tostring), .device_type,
     (.manufacturer // ""), (.model // ""), (.site // "")]
  ) | @csv' > device-export.csv

Bulk Tag Application via API

# Tag all Arista EOS devices as "leaf" and "fabric"
DEVICE_IDS=$(curl -s "http://localhost:3000/api/devices?device_type=arista_eos" \
  -H "Authorization: Bearer ${TOKEN}" | jq -r '.devices[].id')

for DEVICE_ID in ${DEVICE_IDS}; do
  # Get existing tags, append new ones
  EXISTING=$(curl -s "http://localhost:3000/api/devices/${DEVICE_ID}" \
    -H "Authorization: Bearer ${TOKEN}" | jq -r '.tags // [] | join(",")')

  curl -X PUT "http://localhost:3000/api/devices/${DEVICE_ID}" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"tags": ["leaf", "fabric"]}'
  echo "Tagged: ${DEVICE_ID}"
done

Questions & Answers

Q: What bulk actions are available?

A: NetStacks supports these bulk actions on selected devices: Capture Config (backup running configurations), Test Connection (verify SSH connectivity), Add Tags, Remove Tags, Update Credential (change the default credential), Export (download as CSV), and Delete (remove from inventory). Config captures and connection tests run concurrently. Tag, credential, and delete operations are instant metadata updates.

Q: How do I organize devices into groups?

A: Use tags to organize devices into logical groups. Tags are flexible labels that can represent function (core, firewall), environment (production, lab), location (dc-east), or compliance scope (pci). A device can have multiple tags. Filter the device list by tag to quickly select all devices in a group for bulk operations.

Q: How do tags work?

A: Tags are stored as a JSON array on each device record. You can add or remove tags individually or in bulk. Tags are free-form strings with no predefined values — your team defines the taxonomy. The device list filter supports selecting devices by tag, and snapshot collections can target devices by tag through device filters.

Q: Is there a maximum number of devices in a bulk operation?

A: There is no hard limit on selection size. Metadata operations (tags, credentials, delete) scale to thousands of devices with no performance concern. Config capture operations are limited by the concurrency setting and SSH timeout. For very large fleets (1,000+ devices), config captures may take several minutes to complete as the system works through the queue.

Q: How do I monitor bulk operation progress?

A: For config captures, monitor progress on the Snapshots page. The snapshot record shows total devices queued, successful captures, and failures in real time. For metadata operations (tags, credentials), completion is instant and reported immediately in the UI.

Q: Can I undo a bulk operation?

A: Tag additions can be reversed by running a bulk "Remove Tags" operation. Credential updates can be reversed by updating to the previous credential. Device deletions cannot be undone — deleted devices and their backup history are permanently removed. Always export your device list before performing destructive bulk operations.

Troubleshooting

Partial failures in bulk config capture

When a bulk config capture reports some failures, check the snapshot detail page for per-device error messages. Common failure reasons:

• No credential configured — The device has no default credential assigned. Assign a credential to the device or provide a credential override in the collect request.
• SSH connection timeout — The device is unreachable or slow to respond. Verify network connectivity and increase the timeout if needed.
• Authentication failure — The assigned credential has incorrect username/password. Update the credential in the vault.
• Wrong device type — The platform driver sends commands the device does not understand. Correct the device type.

Timeout issues with large batches

When capturing configs from hundreds of devices, the total operation time depends on the concurrency limit and per-device timeout. If the overall operation seems slow:

• Increase the concurrency limit in collection settings (default is typically 10 concurrent connections).
• Ensure the Controller has sufficient CPU and memory for concurrent SSH sessions.
• Consider splitting large batches into multiple snapshots by site or device type.

Tag filter returns unexpected results

Tags are case-sensitive strings. If filtering by tag returns fewer devices than expected, check for case mismatches (e.g., Production vs. production) or trailing spaces. Standardize tag naming conventions across your team to avoid inconsistencies.

Bulk delete removed more devices than expected

If "Select All" was used after filtering, verify the filter was correctly applied before selection. The selection includes all devices matching the current filter, not just the visible page. Always review the confirmation count before confirming a bulk delete.

Related Features

Bulk operations work with device management and snapshot features for fleet-wide workflows:

• Adding Devices — Build your device inventory before performing bulk operations
• Config Snapshots — Bulk config capture creates snapshot collections
• Device Types — Filter devices by platform type for targeted bulk operations
• Credential Folders — Organize credentials that are assigned via bulk credential updates