archived-netvisor/docs/USER_GUIDE.md

User Guide

Complete guide to using NetVisor's features for network discovery, organization, and visualization.

Table of Contents

• Getting Started
• Authentication
• Organizations
• Navigation
• Networks
• Hosts
• Services
• Subnets
• Groups
• Daemons
• API Keys
• Discovery
• Topology Visualization
• Multi-VLAN Setup
• FAQ

Getting Started

First Time Setup

1. Access the UI at http://<your-server-ip>:60072

2. Create your account:

   • Enter an email address
   • Create a password
   • Click Register
   • Alternatively, use OIDC authentication (see Authentication)

3. Onboard:

   • Select the name of your organization and network
   • Decide whether NetVisor should create baseline data for your first network (recommended)

4. Automatic initialization: After onboarding, NetVisor automatically:

   • Starts the integrated daemon (if using default docker-compose with integrated daemon)
   • Begins initial discovery
   • Schedules daily discovery

5. Monitor discovery: Switch to Discover > Sessions to watch the scan progress

5. View results: Once complete (5-10+ minutes), navigate to Topology to see your network diagram

Authentication

NetVisor supports two authentication methods:

Email & Password

Standard authentication with email and password.

Updating credentials: Go to Account in sidebar to change your email or password.

OIDC (OpenID Connect)

NetVisor supports OIDC authentication for enterprise identity providers like Authentik, Keycloak, Auth0, Okta, and others.

Setup: OIDC must be configured by the server administrator. See CONFIGURATION.md for setup instructions.

Linking OIDC: If OIDC is enabled, you can link it to your existing account:

1. Go to Account Settings (user icon in top right)
2. Click Link under your OIDC provider
3. Complete the authentication flow
4. Your account is now linked

Unlinking: You can unlink OIDC at any time, but you'll need to have a password set first.

Organizations

Organizations are the top-level container for users and networks. Every user belongs to exactly one organization.

Organization Roles

These permission levels control what users can do:

Owner

• Everything Admins can do
• Manage organization settings
• Invite Admins

Admin

• Everything Members can do
• View other Admins
• Invite Members
• Remove Members

Member

• Everything Visualizers can do
• Create and edit networks, hosts, services
• Run discovery sessions
• Manage daemons and API keys
• View other members
• Invite Visualizers
• Remove Visualizers

Visualizer

• View topology diagrams

Managing Users

Inviting users:

1. Navigate to Manage > Users
2. Click "Invite User"
3. Select the permission level
4. Click "Generate Link" to create an invite link
5. Share the invite URL with the new user
6. They'll register and automatically join your organization

Viewing users:

• See all organization members in Manage > Users
• View each user's role, authentication method, and join date

Removing users (Owner only):

• Click the delete icon on a user card
• You cannot delete yourself
• You cannot delete the only Owner

Organization Settings

Viewing organization (Owner only):

• Navigate to Manage > Organization to view organization name and plan information

Note: Organizations are automatically created during registration and cannot be manually created or transferred.

Navigation

The NetVisor UI is organized into three main sections:

Sidebar

Topology

Interactive network visualization showing hosts, services, subnets, and their connections.

Discover

Sessions

• Monitor active discovery scans in real-time
• View completed discovery history
• See scan progress, duration, and results

Scheduled

• Create and manage scheduled discoveries
• Configure automatic network scanning
• Set custom cron schedules

Manage

Networks - Organize resources by network environment
Hosts - View and manage discovered devices
Services - Browse all detected services
Subnets - Configure network segments
Groups - Create logical service groupings
Daemons - Manage discovery agents
API Keys - Control daemon authentication
Users - Manage organization members

Settings

Organization - View and edit organization settings (only Owners) Account - View and edit account settings

Networks

Networks are the primary organizational unit in NetVisor. Each network represents a distinct environment with its own hosts, services, and topology.

What Networks Are For

• Separating production, staging, and home environments
• Organizing networks by physical location
• Managing multi-tenant deployments
• Grouping related infrastructure

Network Properties

• Name: Display name for the network
• Description: Optional notes about the network's purpose
• Daemons: Which daemons scan this network
• Hosts: Number of discovered hosts
• Services: Number of detected services

Managing Networks

Creating a network:

1. Navigate to Manage > Networks
2. Click "Create Network"
3. Enter name and optional description
4. Deploy a daemon to scan it

Switching networks: Networks are selected via the topology options panel or when creating discoveries.

Deleting a network: Click the delete icon on the network card. This removes all associated hosts, services, and topology data.

Hosts

Hosts represent physical or virtual devices on your network. They are automatically discovered during network scans.

Host Properties

• Name: Hostname or custom name
• IP Addresses: All network interfaces
• MAC Addresses: Hardware addresses for each interface
• Interfaces: Network connections and subnet membership
• Services: Services running on the host
• Virtualization: Container or VM relationships (if detected)

Managing Hosts

Viewing hosts:

• Navigate to Manage > Hosts
• Filter by network, service type, or search
• Click a host to see detailed information

Editing a host:

1. Click on a host card
2. Modify properties in the detail panel
3. Add/remove interfaces or services
4. Save changes

Creating a host manually:

1. Click "Create Host"
2. Provide name and at least one interface
3. Add services as needed
4. Save

Deleting a host: Click the delete icon. This removes the host and all its interfaces and services.

Consolidating Hosts

When a device appears on multiple VLANs or through different discovery methods, it may be discovered as separate hosts. Use consolidation to merge them.

How to consolidate:

1. Select a host to keep (primary)
2. Click "Consolidate"
3. Select the duplicate host(s) to merge
4. Review the consolidated result
5. Confirm the merge

The primary host will gain all interfaces, services, and properties from the merged hosts.

Host Virtualization

If a host runs Proxmox or Docker, NetVisor tracks which VMs or containers run on it.

Virtualization managers detected:

• Proxmox: Links VMs and LXC containers to the Proxmox service running on the host
• Docker: Links containers to the Docker service running on the host

This relationship is displayed in the topology and host details.

Services

Services represent applications or servers running on hosts. NetVisor automatically detects 50+ common services.

Service Properties

• Name: Service display name
• Definition: Service type (e.g., "Plex", "Home Assistant")
• Category: Classification (Media, Infrastructure, Development, etc.)
• Host: Which host runs this service
• Bindings: Ports and interfaces the service listens on
• Confidence: Detection confidence (System, High, Medium, Low)

Service Categories

Services are organized into categories for filtering and organization:

Infrastructure

• NetworkCore, NetworkAccess, NetworkSecurity
• DNS, VPN, ReverseProxy

Server Services

• Storage, Media, HomeAutomation, Virtualization
• Backup, FileSharing

Applications

• Web, Database, Development, Dashboard
• Monitoring, MessageQueue, Collaboration
• IdentityAndAccess, Communication

Devices

• Workstation, Mobile, IoT, Printer

Other

• AdBlock, Custom, Unknown

Managing Services

Viewing services:

• Navigate to Manage > Services
• Filter by category, host, or network
• Click a service for details

Editing a service:

1. Click on a service card
2. Modify name, bindings, or properties
3. Save changes

Creating a service manually:

1. Navigate to a host's detail view
2. Go to the Services tab
3. Click "Add Service"
4. Select service type and configure bindings
5. Save

Deleting a service: Click the delete icon on the service card.

Subnets

Subnets represent network segments and are used to organize hosts in the topology.

Subnet Properties

• CIDR: Network address and mask (e.g., 192.168.1.0/24)
• Name: Custom name or defaults to CIDR
• Description: Optional notes about the subnet's purpose
• Type: Network classification (LAN, Docker Bridge, Internet, Remote, etc.)

Subnet Types

NetVisor automatically detects subnet types during discovery:

Physical Networks

• LAN: Local area networks
• WiFi: Wireless networks
• IoT: IoT device networks
• Guest: Guest networks

Infrastructure

• Gateway: Gateway interfaces
• VPN Tunnel: VPN connections
• DMZ: Demilitarized zones
• Management: Management networks

Virtual Networks

• Docker Bridge: Docker container networks

Special Types

• Internet: Organizational subnet for public services (uses 0.0.0.0/0)
• Remote: Organizational subnet for remote hosts (uses 0.0.0.0/0)

Organizational Subnets

Subnets with CIDR 0.0.0.0/0 don't represent real networks—they're organizational containers:

Internet Subnet: For public services

• Public DNS servers (1.1.1.1, 8.8.8.8)
• Cloud services
• External APIs

Remote Subnet: For non-local hosts

• Mobile devices
• Remote offices connected via VPN
• Hosts on friend's networks

Managing Subnets

Viewing subnets:

• Navigate to Manage > Subnets
• See all subnets across networks
• Filter by network or type

Editing a subnet:

1. Click on a subnet card
2. Modify name, description, or type
3. Save changes

Creating a subnet:

1. Click "Create Subnet"
2. Enter CIDR and name
3. Select type
4. Save

Deleting a subnet: Click the delete icon. Hosts on the subnet remain but lose subnet association.

Groups

Groups create logical connections between services and hosts for topology visualization.

Group Types

Hub and Spoke

• Central service with connections to multiple others
• Example: API gateway connected to microservices
• Example: Database accessed by multiple applications

Path

• Linear flow through services
• Example: User → Reverse Proxy → Web App → Database
• Example: Client → VPN → Internal Services

Group Properties

• Name: Display name
• Type: Hub and Spoke or Path
• Services: Which services/hosts participate
• Color: Visual styling in topology (optional)

What Groups Do

Groups affect how your topology is displayed:

• Add edges between services to show relationships
• Create visual groupings
• Help document application architectures
• Organize complex network structures

Managing Groups

Creating a group:

1. Navigate to Manage > Groups
2. Click "Create Group"
3. Select type (Hub and Spoke or Path)
4. Choose the central service (Hub and Spoke) or order services (Path)
5. Add related services
6. Save

Editing a group:

1. Click on a group card
2. Modify services or reorder (Path groups)
3. Save changes

Deleting a group: Click the delete icon. This only removes the logical grouping—services and hosts remain.

Use Cases

Web application stack:

Hub: Database
Spokes: Web Server, Background Workers, Admin Panel

Reverse proxy flow:

Path: Internet → Cloudflare → Traefik → Application

Daemons

Daemons are lightweight agents that perform network discovery.

Daemon Properties

• IP Address: Where the daemon is reachable
• Port: Daemon API port (default 60073)
• Network: Which network this daemon scans
• Host: The underlying host running the daemon
• Mode: Whether the daemon will pull work (discovery sessions to run or cancel) from the server, or the server will push work to the daemon
• Created: When the daemon was registered
• Last Seen: Timestamp of last successful heartbeat

Daemon Capabilities

Each daemon reports its capabilities:

Docker Socket Access

• True: Can discover Docker containers
• False: Cannot access Docker socket

Interfaced Subnets

• Lists which subnets the daemon has network interfaces with
• The daemon will scan these subnets by default during network discovery

Managing Daemons

Viewing daemons:

• Navigate to Manage > Daemons
• See all daemons and their capabilities
• Check last seen timestamps

Creating a daemon:

1. Click "Create Daemon"
2. Select target network
3. Click "Generate Key" to create API key
4. Copy the Docker Compose or binary command
5. Run it on your target host

See INSTALLATION.md for deployment instructions.

Deleting a daemon: Click the delete icon. You'll also need to uninstall the daemon from the host it's running on.

Important: Deleting a daemon does NOT delete discovered data. Hosts, services, and topology remain until explicitly deleted.

API Keys

API keys authenticate daemons to the server. Each daemon requires one API key.

API Key Properties

• Name: Custom identifier for the key
• Network: Which network this key grants access to
• Created: When the key was generated
• Last Used: Timestamp of last authentication
• Expires At: Optional expiration date
• Enabled: Whether the key is currently active

Managing API Keys

Viewing API keys:

• Navigate to Manage > API Keys
• See all keys and their usage status

Creating an API key:

1. Go to Manage > Daemons
2. Click "Create Daemon"
3. Click "Generate Key"
4. The key is automatically created and assigned to the network

Alternatively:

1. Go to Manage > API Keys
2. Click "Create API Key"
3. Select target network
4. Set optional expiration
5. Save and copy the key (it won't be shown again)

Disabling an API key:

1. Click on the key card
2. Toggle "Enabled" to off
3. Save

Disabled keys cannot authenticate, but can be re-enabled later.

Deleting an API key: Click the delete icon. Any daemons using this key will stop authenticating and stop working.

Security Best Practices

• Create separate API keys for each daemon
• Use expiration dates for temporary deployments
• Disable unused keys rather than deleting them
• Rotate keys periodically for production environments
• Never share keys in public repositories or logs

Discovery

Discovery is the process of scanning your network to find hosts and services.

Discovery Types

Self-Report

• Daemon reports its own capabilities
• Identifies Docker socket access
• Lists interfaced subnets
• Runs automatically on daemon startup

Network Scan

• Scans IP addresses on configured subnets
• Detects open ports
• Identifies services via pattern matching
• Performs reverse DNS lookups
• Collects MAC addresses (for directly connected subnets)

Docker

• Connects to Docker socket on daemon's host
• Discovers running containers
• Maps container names and metadata
• Detects containerized services
• Identifies internal Docker networks

Run Types

AdHoc (On Demand)

• Manual execution only
• Use for testing or one-time scans
• Triggered from Discover > Sessions

Scheduled (Automatic)

• Runs on a cron schedule
• Default: Every 24 hours (0 0 */1 * * *)
• Enable/disable without deleting

Creating a Discovery

1. Navigate to Discover > Scheduled
2. Click "Create Discovery"
3. Details:
   • Enter a name (e.g., "Daily Network Scan")
   • Select the daemon to execute the discovery
4. Type:
   • Choose discovery type (Network, Docker, or Self-Report)
   • For Network: Select subnets to scan. You can add subnets that the daemon doesn't have a direct interface with, and it will try to reach IP addresses on that subnet as well.
   • For Docker/Self-Report: Automatically uses daemon's host
5. Schedule (optional):
   • Choose AdHoc or Scheduled
   • For Scheduled: Set cron schedule or use preset intervals
6. Save

Running a Discovery

Manual execution:

1. Navigate to Discover > Sessions
2. Find your discovery in the scheduled list
3. Click the "Run" button
4. Monitor progress in real-time

Scheduled execution:

• Scheduled discoveries run automatically at their configured time
• View the "Last Run" timestamp in the scheduled discoveries list

Monitoring Discovery

Real-time progress:

• Navigate to Discover > Sessions
• Active scans show live progress updates
• See scanned count vs. discovered count
• Watch as hosts and services are found

Discovery history:

• Completed discoveries appear in the history list
• View duration, start/end times, and results
• Filter by daemon or network

Discovery Duration

For benchmarking, 1x /24 subnet (256 IP addresses) takes 5-10 minutes to scan in full.

Factors affecting speed:

• Number of IP addresses to scan
• Subnet mask size (smaller masks = more IPs)
• Concurrent scans setting (default: 15)
• Network response times

Host Naming

When discovering hosts, NetVisor determines names using this priority:

1. Hostname from reverse DNS, if available
2. If BestService is set - will use the first named service identified on the host. If IP is set, will use the host's IP address
3. If option 2 didn't produce a name, will use the remaining fallback (ie IP if BestService was set)

Configure this per-discovery in the discovery type settings.

Topology Visualization

The topology view generates an interactive diagram of your network structure.

Topology State

Topology will display different states depending on if the underlying data has changed since it was last built. Pressing Rebuild will have different effects depending on topology state.

Rebuilding the graph will reset some user-provided changes, such as node positions and subnet sizes. Edge handles will be preserved when possible, but may also be overwritten as the layout of the graph may need to change depending on entities being added or removed.

Up to date

- All data is up to date
- There is usually no reason to rebuild the graph in this state

Stale

- One or more entities have been added or updated since the visualization was last rebuilt
- Rebuilding the graph will add those entities

Conflict

- One or more entities on the graph have been deleted since it was last rebuilt
- Rebuilding the graph will remove those entities
- The specific entities that will be removed will be displayed in a modal so you can confirm before they are removed.

Locked

- Other states will not be displayed
- Topology cannot be rebuilt
- Press Lock to enter the locked state

Visual Elements

Subnet Containers

• Large rectangles grouping hosts by network segment
• Shows subnet name and CIDR
• Can be resized manually

Interface Nodes

• Represent network interfaces
• Show services bound to that interface
• Display IP addresses and hostnames

Services

• Icons representing detected services
• Show service name and ports

Edges

• Lines connecting related nodes
• Different types:
  • Host interfaces
  • Group relationships
  • Docker container links

Left Zone

• Optional section within each subnet
• Can display infrastructure services separately
• Customizable title and service categories

Customization Options

Access the options panel via the button on the right side of the topology view:

Visual Options

Don't Fade Edges

• Show all edges at full opacity
• Default behavior fades unselected edges
• Enable for clearer edge visibility and screenshot appearance

Hide Resize Handles

• Remove subnet resize handles from corners
• Cleaner screenshot appearance
• Re-enable to adjust subnet sizes

Docker Options

Group Docker Bridges

• Display all containers on a host in one subnet grouping
• Off: Each Docker bridge gets its own subnet container
• On: All Docker containers grouped under one subnet per host

Hide VM Provider on Containers

• Don't indicate the VM provider for containerized services
• Useful when virtualization hierarchy is obvious
• Reduces visual noise

Left Zone Options

Custom Title

• Change the "Infrastructure" label to your preference
• Examples: "Core Services", "Network", "Foundation"
• Applied to all subnets

Service Categories

• Select which categories appear in the left zone
• Default: DNS and ReverseProxy
• Common choices: Add VPN, Monitoring

Show Gateway in Left Zone

• Display gateway services in the left zone
• Off: Gateways appear in the main subnet area
• On: Gateways separated in left zone

Hide Options

Hide Ports

• Don't show port numbers next to services
• Cleaner appearance
• Re-enable to see listening ports

Service Categories

• Select categories to completely hide from topology
• More aggressive than filtering
• Use to remove entire classes of services

Edge Types

• Hide specific connection types
• Options: Interface, Gateway, Group, Container
• Simplifies complex topologies

Manual Adjustments

Node Positioning

• Click and drag any node to reposition

Edge Handle

• Select an edge to show handles (same-colored circle at edge ends)
• Move handles to other locations on node

Subnet Sizing

• Drag subnet corners to resize
• Useful for fitting many hosts

Exporting

Export your topology as a PNG image:

1. Customize your topology as desired
2. Click the Export button in the topology header
3. PNG file downloads automatically with timestamp
4. Image includes all current customizations

Use cases:

• Documentation
• Presentations
• Sharing with team members
• Progress tracking

Multi-VLAN Setup

To map networks across multiple VLANs, deploy additional daemons or select additional subnets in Discovery > Scheduled.

Why Multiple Daemons?

Adding subnets to a scan works, but the daemon isn't guaranteed to be able to reach those subnets depending on your network firewall and other configurations, and it won't be able to get MAC Addresses or Hostnames from DNS.

For isolated VLANs:

• Deploy one daemon per VLAN
• Each daemon scans its local network segment
• Server merges data into unified topology

Deployment Strategy

Option 1: Daemon per VLAN (Recommended)

1. Identify your VLANs:

   • Production (192.168.1.0/24)
   • IoT (192.168.2.0/24)
   • Guest (192.168.3.0/24)

2. Deploy a daemon on each network:

   • Place a host on each VLAN (or use a router/firewall with access)
   • Install daemon following INSTALLATION.md
   • Configure with appropriate network ID

3. Run discoveries:

   • Each daemon scans its local VLAN
   • Server consolidates results automatically

Option 2: Configure Subnets Daemon Can Reach

If your daemon can route to multiple VLANs (e.g., it's on a management network):

1. Create subnets for each VLAN in Manage > Subnets
2. Create a Network Scan discovery in Discover > Scheduled
3. Select all reachable subnets
4. Run the discovery

Note: Without direct interface, the daemon cannot collect MAC addresses or hostnames via DHCP.

Handling Duplicate Hosts

Devices appearing on multiple VLANs may be discovered as separate hosts. Use the Consolidate Hosts feature to merge them:

1. Identify the duplicate hosts (same device, different IPs)
2. Select the primary host to keep
3. Click "Consolidate"
4. Select the duplicate(s) to merge
5. Confirm

The primary host will have interfaces on all VLANs.

FAQ

Is IPv6 supported?

Not currently. IPv6 support is planned for future releases:

Planned features:

• Collecting and displaying IPv6 addresses during discovery
• Manual entry of IPv6 addresses when editing hosts
• IPv6 connectivity testing for known hosts

Not planned:

• Full IPv6 subnet scanning (would take too long for /64 networks)

If you need IPv6 support sooner, open an issue describing your use case.

What services can NetVisor discover?

NetVisor automatically detects 200+ common services including:

Infrastructure & Networking: Pi-hole, AdGuard Home, Unifi Controller, pfSense, OPNsense
Virtualization & Containers: Proxmox, Docker, Kubernetes, Portainer
Databases: PostgreSQL, MySQL/MariaDB, MongoDB, Redis, Microsoft SQL Server
Web Servers & Proxies: Apache, Nginx, Lighttpd, Traefik, Caddy, HAProxy
Monitoring & Observability: Grafana, Prometheus, Zabbix, Netdata, Nagios
Storage & File Sharing: Synology DSM, QNAP, TrueNAS, Nextcloud, Samba, Windows File Server
Development & CI/CD: GitLab, Jenkins, Ansible AWX, GitHub Enterprise, Azure DevOps
Communication & Collaboration: Microsoft Exchange, Asterisk, FreePBX, Rocket.Chat
Media & Content: Plex, Jellyfin, Emby, streaming servers
Automation & IoT: Home Assistant, Node-RED, MQTT brokers

For the complete list, see the service definitions directory.

Service not detected?

• Report it: Service detection issue
• Request it: Missing service
• Contribute: Service definition guide

How do I contribute?

We welcome contributions! See contributing.md for:

• Adding service definitions (great first contribution!)
• Reporting bugs
• Requesting features
• Submitting pull requests

Join our Discord community for help and discussions.

Update NETVISOR_INTEGRATED_DAEMON_URL to match if using the integrated daemon.

See CONFIGURATION.md for more options.

How do I backup my data?

NetVisor stores all data in PostgreSQL. To backup:

Docker setup:

# Backup
docker exec netvisor-db pg_dump -U postgres netvisor > netvisor_backup.sql

# Restore
docker exec -i netvisor-db psql -U postgres netvisor < netvisor_backup.sql

Manual setup: Use standard PostgreSQL backup tools (pg_dump, pg_restore).

How do I reset my password?

Currently, password resets must be done directly in the database:

1. Generate a new password hash using bcrypt
2. Update the users table with the new hash
3. Or, ask another Owner to delete and re-invite you

Self-service password reset is planned for a future release.

Why is my topology empty after discovery?

Check these common issues:

1. Discovery failed: View Discover > Sessions for errors
2. Wrong network selected: Check topology options panel for network filter
3. All services hidden: Check if service category filters are too aggressive
4. No hosts found: Verify daemon can reach the network

See INSTALLATION.md for more troubleshooting steps.

---

Need help? Join our Discord or open an issue.