Zabbix Device Sync

Zabbix Device Sync: Automated Network Device Synchronization with rConfig V8

Zabbix Device Sync enables automated synchronization of network device inventory from Zabbix monitoring platform into rConfig V8. This integration extracts device information from Zabbix, transforms it using tag-based mappings, and imports devices through a staging process for administrator review before production deployment.

Platform	rConfig V8 Support	Platform Version Tested
Zabbix	✓ Verified	6.4.10+, 7.0+

How It Works

The Zabbix Device Sync follows an ETL (Extract, Transform, Load) pattern with a review stage:

Extract: Connect to Zabbix API and retrieve device inventory based on configured host groups or tags
Transform & Map: Parse Zabbix host data and apply rConfig-specific tag mappings
Load to Staging: Import transformed devices into staging table for review
Review & Approve: Administrator validates staged devices and resolves any issues
Deploy: Import approved devices into main rConfig device inventory
Schedule: Automated sync jobs keep inventory synchronized with Zabbix

This idempotent process prevents duplicate device creation and maintains consistency across synchronizations. Staging tables are cleared after successful deployment to production.

Prerequisites

Before configuring Zabbix Device Sync, ensure you have:

Zabbix requirements:

Zabbix 6.4.10 or later
Administrator access to Zabbix
API user with read permissions: host.get, hostgroup.get, user.get, usergroup.get
Devices organized in host groups or tagged for filtering
Network connectivity between Zabbix and rConfig servers

rConfig requirements:

rConfig V8 Professional
Administrator access to rConfig
Credential sets configured for device authentication
Device templates, vendors, categories, and tags created

Zabbix host tagging:

All hosts to be synchronized must have the following rConfig-specific tags applied in Zabbix:

Tag Name	Required	Description
`rconfig::template`	Yes	Device template name or ID
`rconfig::credentialset`	Yes	Credential set name or ID
`rconfig::vendor`	Yes	Vendor name or ID
`rconfig::category`	Yes	Category name or ID
`rconfig::tag`	No	Comma-separated tag names or IDs
`rconfig::model`	No	Device model string
`rconfig::prompt`	No	Command prompt regex pattern
`rconfig::enable_prompt`	No	Enable prompt regex pattern

Configure Zabbix

Step 1: Create API User

Create a Zabbix user with API access:

Navigate to Administration > Users in Zabbix
Click Create user
Configure user settings:
- Username: rconfig-api
- Password: Set secure password
- Role: User with API access
Assign user to appropriate user groups
Save the user

Step 2: Set API Permissions

Ensure the API user has the following permissions:

host.get - Read host information
hostgroup.get - Read host group information
user.get - Read user information
usergroup.get - Read user group information

These permissions can be set in User roles configuration.

Step 3: Tag Devices for Sync

Apply rConfig-specific tags to Zabbix hosts:

Navigate to Configuration > Hosts
Select a host to edit
Go to Tags tab
Add required rConfig tags:

Example tagging:

rconfig::template = Cisco IOS
rconfig::credentialset = Production Network
rconfig::vendor = Cisco
rconfig::category = Routers
rconfig::tag = Core,Production
rconfig::model = Catalyst 9300
rconfig::prompt = {HOST.NAME}[>#]
rconfig::enable_prompt = {HOST.NAME}[>#]

Save the host configuration
Repeat for all hosts to be synchronized

Step 4: Organize Hosts (Optional)

Organize hosts using host groups or tags for filtering:

Create host groups for device categories (e.g., “Production Routers”, “Branch Switches”)
Apply consistent tagging across similar device types
Use Zabbix templates to inherit tags automatically

Configure rConfig V8

Step 1: Access Integration Settings

Navigate to Settings > Integrations in rConfig and click Configure on the Zabbix integration.

Step 2: Configure Connection Settings

Complete the Zabbix integration form:

Integration Name:

Descriptive name for this integration (e.g., “Production Zabbix”)

Zabbix Base URL:

Full URL to Zabbix server (e.g., https://zabbix.example.com)

Zabbix API User:

Username created in Zabbix for API access

Zabbix API Password:

Password for the API user

SSL Verification:

Verify SSL Peer: Uncheck if using self-signed certificates
SSL Verify Host: Uncheck if using self-signed certificates

Step 3: Configure Filters

Select which Zabbix hosts to synchronize using host groups or tags:

By Host Group:

Select one or more host groups to sync
Click Add host group after selection

By Tag:

Enter tag name and value
Click Add tag after entry
Add multiple tags as needed

Example filter configurations:

Host Groups: Linux servers, Windows servers, Network devices
Tags: Environment:Production, Location:DataCenter1

Step 4: Save and Test Connection

Click Save to store the configuration.

Test Connection:

Click Test Connection button
Verify successful connection to Zabbix API
Review connection status message

Test Credentials:

Click Test Credentials button
Successful test returns the first user in Zabbix system
Verify API permissions are correct

Extract Devices from Zabbix

Step 1: Access Extract Tab

Click Next on the configuration screen or navigate to the Extract List tab.

Step 2: Run Extraction

Click Run extract from Zabbix to retrieve devices from Zabbix.

The extraction process:

Connects to Zabbix API
Retrieves hosts based on configured filters
Extracts host properties and tags
Displays results in extract list table

Step 3: Review Extracted Devices

Review the extracted device list:

View in Zabbix: Opens device directly in Zabbix interface
Delete: Remove device from extract list (will re-import on next automated run)
Expand row: View detailed host information from Zabbix

Inherited tags: All tags inherited from Zabbix templates are included in the extraction. Inherited tags overwrite host-specific tags, except for rconfig::tag which merges with existing tags.

Host groups as tags: If enabled in configuration, Zabbix host groups are imported as tags and applied to devices in rConfig.

Transform and Map Devices

Step 1: Run Transformation

Click Run Transform & Mapping to process extracted devices.

The transformation process:

Parses rConfig-specific tags from Zabbix hosts
Maps tag values to rConfig templates, vendors, categories
Validates required tags are present
Checks that referenced rConfig resources exist
Flags any devices with validation errors

Step 2: Review Transformation Results

After transformation, the extract list updates:

Expandable rows: Show mapped rConfig properties for each device
Status indicators: Show whether device is ready for import
Validation messages: Display any errors preventing import

Dynamic tag creation: Tags specified in rconfig::tag with textual values (not IDs) are automatically created in rConfig if they don’t exist.

Common validation errors:

Missing required tags
Invalid template, vendor, or category names/IDs
Credential set not found
Duplicate hostnames

Step 3: Check Logs

Click Status & Logs tab to view detailed transformation logs:

Successful transformations
Validation errors with device names
Tag mapping issues
Resource not found errors

Load to Staging Table

Step 1: Load Devices

Click Load to Device Staging Table to import transformed devices.

The loading process:

Validates all devices in extract list
Imports valid devices to staging table
Skips devices with validation errors
Maintains staging table for review

Step 2: Review Staged Devices

The staging table displays:

All devices ready for import
Expandable rows showing complete rConfig property mappings
Final validation status
Device details as they will appear in rConfig

Staging table actions:

Run assessment: Execute full ETL process up to staging (no deployment)
Run full deployment: Complete ETL process and import to production devices
Manual review: Examine individual devices before deployment

Deploy to Production

Option 1: Manual Deployment

Review staged devices and click Run full deployment when ready.

The deployment process:

Validates staged devices one final time
Creates devices in main rConfig device inventory
Links devices to templates, vendors, categories, tags
Assigns credential sets
Schedules immediate configuration backups
Clears staging table
Logs deployment results

Option 2: Automated Assessment

Click Run assessment to test the full process without deploying:

Executes extract, transform, and load to staging
Does not deploy to production devices
Useful for validating configuration before automated runs
Staging table remains populated for review

Verify Imported Devices

View Devices in rConfig

Navigate to Devices to view newly imported devices.

Integration indicator: Imported devices display an integration icon next to the hostname, showing the device source.

Device details: Click a device to view full details. Integration-sourced devices include:

View in Zabbix button linking to Zabbix host
Integration host ID stored for API reference
Source integration name in device metadata

API access: Use the integration host ID to download configurations via API:

Endpoint: /settings/restapi-docs/download-now
Parameter: integration_host_id
Returns latest device configuration

Schedule Automated Sync

Step 1: Create Scheduled Task

Navigate to Scheduled Tasks and click Add Task.

Step 2: Configure Task

Task Type: Select Integration Job from dropdown

Task Name: Descriptive name (e.g., “Daily Zabbix Sync”)

Task Description: Optional description of sync purpose

Step 3: Select Integration

Choose the Zabbix integration configured in previous steps.

Step 4: Set Schedule

Configure sync frequency:

Daily: Run at specific time each day
Weekly: Run on specific day and time
Monthly: Run on specific date and time
Cron expression: Custom schedule using cron syntax

Example schedules:

Daily at 2:00 AM: 0 2 * * *
Every 6 hours: 0 */6 * * *
Monday through Friday at 1:00 AM: 0 1 * * 1-5

Step 5: Review and Save

Review task settings and click Save.

The scheduled task will:

Run full ETL process automatically
Extract devices from Zabbix
Transform and map using configured tags
Load to staging table
Deploy valid devices to production
Log all activities

CLI Commands

Main Integration Command

php /var/www/html/rconfig8/current/artisan rconfig:integration-zabbix

Running without options displays available commands:

Available options:

Option	Shortcut	Description
`--connection`	`-c`	Test connection to Zabbix API
`--usertest`	`-u`	Test API user credentials
`--extract`	`-e`	Extract devices from Zabbix
`--transform`	`-t`	Transform and map devices
`--mapping`	`-m`	Run mapping process
`--load`	`-l`	Load devices to staging table
`--assessment`	`-a`	Run full process without deployment
`--deployment`	`-d`	Run full process and deploy to production

Example command sequences:

# Test connection
php artisan rconfig:integration-zabbix --connection

# Full assessment (no deployment)
php artisan rconfig:integration-zabbix --assessment

# Production deployment
php artisan rconfig:integration-zabbix --deployment

Single Device Sync Command

Synchronize an individual Zabbix device through the complete ETL workflow with verbose debugging output:

php /var/www/html/rconfig8/current/artisan rconfig:integration-zabbix-single-device {zabbix_host_id} [options]

Parameters:

{zabbix_host_id}: Zabbix host ID to synchronize (required)

Options:

-a, --assessment: Run all ETL steps in sequence for testing, but does not load data into devices table
-d, --deployment: Process single Zabbix device through ETL and deploy to production
-h, --help: Display help for the given command
--silent: Do not output any message
-q, --quiet: Only errors are displayed. All other output is suppressed
-V, --version: Display this application version
--ansi|--no-ansi: Force (or disable —no-ansi) ANSI output
-n, --no-interaction: Do not ask any interactive question
--env[=ENV]: The environment the command should run under
-v|vv|vvv, --verbose: Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Use cases:

Troubleshoot individual device:

# Process single device with verbose output
php artisan rconfig:integration-zabbix-single-device 59919 -v

Test device mapping:

# Extract, transform, and stage single device
php artisan rconfig:integration-zabbix-single-device 59919 --assessment

Quick device import:

# Import single device directly to production
php artisan rconfig:integration-zabbix-single-device 59919 --deployment

Workflow:

Extracts specified Zabbix host using host ID
Transforms host data using rConfig tag mappings
Validates required tags and referenced resources
Loads to staging table for review
Deploys to production (if -d flag used)
Outputs detailed process information and any errors

Example output:

$ php artisan rconfig:integration-zabbix-single-device 59919 -d

Processing Zabbix Host ID: 59919
✓ Extracting host from Zabbix
✓ Host found: core-router-01.example.com
✓ Transforming host data
✓ Mapping tags: template=Cisco IOS, vendor=Cisco, category=Routers
✓ Validating required tags
✓ Loading to staging table
✓ Deploying to production devices
✓ Device created: core-router-01.example.com
✓ Scheduling initial configuration backup

Single device sync completed successfully.

Troubleshooting

Connection test fails

Check Zabbix URL: Verify base URL is correct and accessible from rConfig server

Verify SSL settings: Disable SSL verification for self-signed certificates

Test network connectivity: Ensure firewall allows traffic between rConfig and Zabbix

Check Zabbix API status: Verify Zabbix API is enabled and responding

Credential test fails

Verify username and password: Confirm API user credentials are correct

Check user permissions: Ensure API user has required read permissions

Review Zabbix user status: Confirm user is enabled and not locked

Test authentication: Log in to Zabbix web interface with same credentials

No devices extracted

Verify filters: Check host group or tag filters match Zabbix hosts

Review host visibility: Ensure API user can see target hosts in Zabbix

Check host status: Confirm hosts are enabled in Zabbix

Validate filter syntax: Verify tag names and values are spelled correctly

Transformation errors

Missing required tags: Add all required rConfig tags to Zabbix hosts

Invalid tag values: Verify template, vendor, category names/IDs exist in rConfig

Tag format issues: Ensure tag values match expected format (no extra spaces)

Check logs: Review Status & Logs tab for specific validation errors

Devices fail to deploy

Duplicate hostnames: Check for existing devices with same hostname in rConfig

Credential set errors: Verify credential sets exist and are accessible

Template errors: Confirm device templates are properly configured

Database constraints: Review Laravel logs for database errors

Single device sync fails

Invalid Zabbix host ID: Verify host ID exists in Zabbix

Host not accessible: Ensure API user can access the specific host

Missing tags: Check host has all required rConfig tags in Zabbix

Use verbose flag: Run with -v option to see detailed error information

Scheduled sync not running

Verify task enabled: Check scheduled task is active

Review cron schedule: Ensure cron expression is valid

Check task logs: View scheduled task execution history

Verify queue workers: Ensure Horizon/queue workers are running

Best Practices

Start with test group: Create a small Zabbix host group for initial testing before full-scale sync.

Consistent tagging: Establish tag naming standards and apply consistently across Zabbix inventory.

Use templates: Apply rConfig tags to Zabbix templates for automatic inheritance by hosts.

Test single devices: Use single device sync command to validate mappings before bulk operations.

Regular monitoring: Check sync logs regularly for errors or validation issues.

Staged review: Use assessment mode to preview imports before deploying to production.

Document mappings: Maintain documentation of tag mappings and filter configurations.

Schedule wisely: Run automated syncs during low-activity periods to minimize impact.

Backup before bulk imports: Create rConfig backup before first large-scale deployment.

Device Sync Overview - Understanding device synchronization concepts
Nautobot Sync Setup - Configure Nautobot integration
NetBox Sync Setup - Configure NetBox integration
Device Management - Managing devices in rConfig
Scheduled Tasks - Automating sync operations