mirrors/thatmattlove-hyperglass
1
0
Fork 1
mirror of https://github.com/thatmattlove/hyperglass.git synced 2026-04-17 13:28:27 +00:00
Code Issues Activity

docs: Add comprehensive configuration documentation and user guide

Browse source 
- Add complete configuration reference (complete-config.mdx) with detailed parameter documentation, examples, and descriptions for all config.yaml options
- Add user guide (user-guide.mdx) explaining hostname resolution, 'My IP' feature, query types, and troubleshooting for end users
- Add quick-start configuration examples (quick-start.mdx) with 8 real-world scenarios: minimal, corporate, privacy-focused, high-performance, ISP, enterprise, development, and monitoring setups
- Update navigation structure (_meta.tsx files) to integrate new documentation sections
- Provide comprehensive coverage of DNS-over-HTTPS hostname resolution, myip.wtf IP detection, web UI customization, logging/webhooks, structured output, and theme configuration
- Include practical examples, use cases, troubleshooting tips, and best practices throughout

This addresses documentation gaps by providing both technical reference material for administrators and user-focused guidance for end users, with extensive real-world configuration examples.
This commit is contained in:
Wilhelm Schonfeldt 2025-09-26 12:12:27 +02:00
parent 7a6388bd39
commit 8f7fcac4b1
6 changed files with 1624 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
docs/pages/_meta.tsx
View file

@ -3,6 +3,7 @@ export default {
"---": {
type: "separator",
},
"user-guide": "User Guide",
installation: "Installation",
configuration: "Configuration",
platforms: "Platforms",

4
docs/pages/configuration/config/_meta.tsx
View file

@ -1,4 +1,8 @@
export default {
"complete-config": "Complete Configuration Reference",
"---": {
type: "separator",
},
"api-docs": "API Docs",
caching: "Caching",
logging: "Logging & Webhooks",

800
docs/pages/configuration/config/complete-config.mdx Normal file
View file

@ -0,0 +1,800 @@
---
title: Complete Configuration Reference
description: Comprehensive documentation for all config.yaml parameters with examples
---
import { Callout } from 'nextra/components'
import { DocsButton } from '~/components/docs-button'
# Complete Configuration Reference
This is a comprehensive reference for all available configuration options in hyperglass. The configuration is written in YAML format and saved as `config.yaml` in your hyperglass configuration directory.
## Top-Level Parameters
These parameters are configured at the root level of your `config.yaml` file.
### Basic Site Information
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `site_title` | String | `hyperglass` | The name of your hyperglass site. Used in HTML `<title>` tags and API documentation. |
| `org_name` | String | `Beloved Hyperglass User` | Your organization's name. Used in UI, API documentation, and HTML meta tags for SEO. |
| `site_description` | String | `{org_name} Network Looking Glass` | Short description of your site. Used for HTML meta description tag. `{org_name}` is automatically replaced. |
| `primary_asn` | String/Integer | `65001` | Your network's primary ASN. Used for defaults like subtitle and PeeringDB URL. |
#### Example: Basic Site Configuration
```yaml filename="config.yaml"
site_title: "ACME Networks Looking Glass"
org_name: "ACME Networks Inc."
site_description: "Network diagnostic tools for ACME Networks AS65000"
primary_asn: 65000
```
### System Parameters
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `request_timeout` | Integer | `90` | Global timeout in seconds for all requests. Frontend uses this exact value; backend uses value minus 1 second. |
| `fake_output` | Boolean | `false` | Enable fake static output for development/testing purposes. |
| `cors_origins` | Array | `[]` | List of allowed CORS hosts. By default, no CORS hosts are allowed. |
| `plugins` | Array | `[]` | List of paths to custom plugin files. |
#### Example: System Configuration
```yaml filename="config.yaml"
request_timeout: 120
fake_output: false # Set to true for testing
cors_origins:
- "https://network-tools.example.com"
- "https://monitoring.example.com"
plugins:
- "/etc/hyperglass/plugins/custom_validation.py"
```
---
## Cache Configuration
Controls how hyperglass caches query responses to improve performance.
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `cache.timeout` | Integer | `120` | Cache timeout in seconds. How long responses are cached. |
| `cache.show_text` | Boolean | `true` | Whether to show cache timeout countdown to users. |
#### Example: Cache Configuration
```yaml filename="config.yaml"
cache:
timeout: 300 # Cache for 5 minutes
show_text: true # Show "Results cached for X seconds" to users
```
---
## API Documentation Configuration
Controls the automatically generated API documentation available at `/api/docs`.
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `docs.enable` | Boolean | `true` | Enable or disable API documentation. |
| `docs.base_url` | String | `https://lg.example.net` | Base URL used in API request samples. |
| `docs.path` | String | `/api/docs` | HTTP path where API documentation is accessible. |
| `docs.title` | String | `{site_title} API Documentation` | API documentation title. `{site_title}` is automatically replaced. |
| `docs.description` | String | `` | Description appearing below the API documentation title. |
| `docs.mode` | String | `redoc` | Documentation UI style: `redoc` or `swagger`. |
### API Endpoint Documentation
Each API endpoint's documentation can be customized:
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `docs.query.title` | String | Title for the query submission endpoint |
| `docs.query.description` | String | Description for the query submission endpoint |
| `docs.query.summary` | String | Summary text for the query submission endpoint |
| `docs.devices.title` | String | Title for the devices list endpoint |
| `docs.devices.description` | String | Description for the devices list endpoint |
| `docs.devices.summary` | String | Summary text for the devices list endpoint |
| `docs.queries.title` | String | Title for the supported queries endpoint |
| `docs.queries.description` | String | Description for the supported queries endpoint |
| `docs.queries.summary` | String | Summary text for the supported queries endpoint |
| `docs.info.title` | String | Title for the system information endpoint |
| `docs.info.description` | String | Description for the system information endpoint |
| `docs.info.summary` | String | Summary text for the system information endpoint |
#### Example: API Documentation Configuration
```yaml filename="config.yaml"
docs:
enable: true
base_url: "https://lg.acmenetworks.com"
path: "/api/docs"
title: "ACME Networks Looking Glass API"
description: "RESTful API for network diagnostic queries"
mode: "redoc"
# Customize individual endpoints
query:
title: "Execute Network Query"
description: "Submit traceroute, ping, or BGP lookup requests"
summary: "Network Diagnostics"
devices:
title: "Network Locations"
description: "Available routers and their capabilities"
summary: "Router List"
```
---
## Logging & Webhooks Configuration
Controls log output, file logging, syslog, and HTTP webhooks for query notifications.
### File Logging
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `logging.directory` | Path | `/tmp` | Directory where log files are stored. |
| `logging.format` | String | `text` | Log format: `text` or `json`. |
| `logging.max_size` | Size | `50MB` | Maximum log file size before rotation. |
### Syslog
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `logging.syslog.enable` | Boolean | `true` | Enable syslog logging. |
| `logging.syslog.host` | String | | Syslog server hostname or IP address. |
| `logging.syslog.port` | Integer | `514` | Syslog server port. |
### HTTP Webhooks
Send query notifications to external systems (Slack, Teams, custom endpoints).
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `logging.http.enable` | Boolean | `true` | Enable HTTP webhook logging. |
| `logging.http.provider` | String | `generic` | Webhook provider: `slack`, `msteams`, or `generic`. |
| `logging.http.host` | URL | | Webhook endpoint URL. |
| `logging.http.verify_ssl` | Boolean | `true` | Verify SSL certificates for HTTPS webhooks. |
| `logging.http.timeout` | Number | `5.0` | Webhook request timeout in seconds. |
| `logging.http.headers` | Object | `{}` | Custom HTTP headers to send with webhooks. |
| `logging.http.params` | Object | `{}` | Custom URL parameters to send with webhooks. |
#### Authentication for HTTP Webhooks
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `logging.http.authentication.mode` | String | `basic` | Authentication mode: `basic` or `api_key`. |
| `logging.http.authentication.username` | String | | Username for basic authentication. |
| `logging.http.authentication.password` | String | | Password for basic auth or API key value. |
| `logging.http.authentication.header` | String | `x-api-key` | Header name for API key authentication. |
#### Example: Complete Logging Configuration
```yaml filename="config.yaml"
logging:
directory: "/var/log/hyperglass"
format: "json"
max_size: "100MB"
# Send logs to syslog server
syslog:
enable: true
host: "syslog.example.com"
port: 514
# Send query notifications to Slack
http:
enable: true
provider: "slack"
host: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
timeout: 10.0
verify_ssl: true
```
#### Example: Custom Webhook with API Key
```yaml filename="config.yaml"
logging:
http:
enable: true
provider: "generic"
host: "https://monitoring.example.com/webhook"
authentication:
mode: "api_key"
password: "your-secret-api-key"
header: "Authorization"
headers:
"Content-Type": "application/json"
"User-Agent": "hyperglass-webhook"
```
---
## Messages Configuration
Customize error messages and user-facing text shown in the UI and API responses.
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `messages.no_input` | String | `{field} must be specified.` | Shown when required field is missing. `{field}` shows field name. |
| `messages.target_not_allowed` | String | `{target} is not allowed.` | Shown when query target is denied by rules. `{target}` shows denied target. |
| `messages.feature_not_enabled` | String | `{feature} is not enabled.` | Shown when disabled query type is requested. `{feature}` shows feature name. |
| `messages.invalid_input` | String | `{target} is not valid.` | Shown for invalid query target values. `{target}` shows invalid input. |
| `messages.invalid_query` | String | `{target} is not a valid {query_type} target.` | Shown for query type/target mismatches. |
| `messages.invalid_field` | String | `{input} is an invalid {field}.` | Shown for invalid field values. |
| `messages.general` | String | `Something went wrong.` | Generic error message for unexpected errors. |
| `messages.not_found` | String | `{type} '{name}' not found.` | Shown when configuration object doesn't exist. |
| `messages.request_timeout` | String | `Request timed out.` | Shown when request exceeds timeout limit. |
| `messages.connection_error` | String | `Error connecting to {device_name}: {error}` | Shown for device connection failures. |
| `messages.authentication_error` | String | `Authentication error occurred.` | Shown for device authentication failures. |
| `messages.no_response` | String | `No response.` | Shown when no output can be read from device. |
| `messages.no_output` | String | `The query completed, but no matching results were found.` | Shown for successful queries with empty results. |
#### Example: Custom Messages
```yaml filename="config.yaml"
messages:
no_input: "Please specify a {field} for your query."
target_not_allowed: "Sorry, {target} is not permitted by our policy."
request_timeout: "Your request took too long and was cancelled."
connection_error: "Unable to reach {device_name}: {error}"
no_output: "Query executed successfully but returned no results."
```
---
## Structured Output Configuration
Controls how hyperglass processes and displays structured data from network devices.
### BGP Communities
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `structured.communities.mode` | String | `deny` | How to handle communities: `permit`, `deny`, or `name`. |
| `structured.communities.items` | Array | `[]` | List of community strings to permit/deny. |
| `structured.communities.names` | Object | `{}` | Map community values to human-readable names. |
### RPKI Validation
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `structured.rpki.mode` | String | `router` | RPKI validation source: `router` or `external`. |
| `structured.rpki.backend` | String | `cloudflare` | External RPKI validation backend to use. |
| `structured.rpki.rpki_server_url` | String | `` | Custom RPKI validation server URL. |
#### Example: Structured Output Configuration
```yaml filename="config.yaml"
structured:
communities:
mode: "name" # Show human-readable names
names:
"65000:100": "Customer Routes"
"65000:200": "Peer Routes"
"65000:300": "Upstream Routes"
"65000:999": "Blackhole"
rpki:
mode: "external" # Use external RPKI validation
backend: "cloudflare" # Use Cloudflare's RPKI API
```
---
## Web UI Configuration
Extensive customization options for the web interface appearance and behavior.
### Basic Web Settings
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `web.location_display_mode` | String | `auto` | Location selector style: `auto`, `dropdown`, or `gallery`. |
| `web.custom_javascript` | Path | | Path to custom JavaScript file to load. |
| `web.custom_html` | Path | | Path to custom HTML content to display. |
### DNS over HTTPS
Controls hostname resolution in the browser using DNS-over-HTTPS.
<Callout type="info">
When users enter hostnames (like `example.com`) instead of IP addresses, hyperglass uses DNS-over-HTTPS to resolve them to IP addresses directly in the user's browser. This provides privacy and security benefits over traditional DNS queries.
</Callout>
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `web.dns_provider.name` | String | `cloudflare` | DNS provider: `cloudflare`, `google`, or `custom`. |
| `web.dns_provider.url` | String | Auto-detected | Custom DNS-over-HTTPS endpoint URL. |
#### Example: DNS Configuration
```yaml filename="config.yaml"
web:
dns_provider:
name: "cloudflare" # Privacy-focused option
# Or use a custom DNS resolver:
web:
dns_provider:
name: "custom"
url: "https://dns.example.com/dns-query"
```
### Logo Configuration
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `web.logo.light` | Path | Built-in logo | Logo image for light theme. |
| `web.logo.dark` | Path | Built-in logo | Logo image for dark theme. |
| `web.logo.favicon` | Path | Built-in icon | Favicon/icon image. |
| `web.logo.width` | String | `50%` | Logo width (percentage or pixels). |
| `web.logo.height` | String | | Logo height (percentage or pixels). |
#### Example: Custom Logo
```yaml filename="config.yaml"
web:
logo:
light: "/etc/hyperglass/images/company-logo-light.svg"
dark: "/etc/hyperglass/images/company-logo-dark.svg"
favicon: "/etc/hyperglass/images/company-icon.svg"
width: "200px"
height: "60px"
```
### Greeting Modal
Show a welcome message or terms of service when users first visit.
<Callout type="info">
The greeting modal is perfect for displaying terms of service, usage policies, or welcome messages. When `required` is set to `true`, users cannot use the looking glass until they acknowledge the greeting.
</Callout>
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `web.greeting.enable` | Boolean | `false` | Enable the greeting modal. |
| `web.greeting.file` | Path | | Path to markdown/text file with greeting content. |
| `web.greeting.title` | String | `Welcome` | Greeting modal title. |
| `web.greeting.button` | String | `Continue` | Greeting acknowledgment button text. |
| `web.greeting.required` | Boolean | `false` | Whether users must acknowledge before using the looking glass. |
#### Example: Terms of Service Greeting
```yaml filename="config.yaml"
web:
greeting:
enable: true
title: "Terms of Service"
file: "/etc/hyperglass/terms-of-service.md"
button: "I Agree"
required: true # Users must agree to proceed
```
### Text Customization
Customize almost all text displayed in the user interface.
#### Basic Interface Text
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `web.text.title` | String | `hyperglass` | Main title text. |
| `web.text.subtitle` | String | `Network Looking Glass` | Subtitle text. |
| `web.text.query_location` | String | `Location` | Label for location/router selection field. |
| `web.text.query_type` | String | `Query Type` | Label for query type selection field. |
| `web.text.query_target` | String | `Target` | Label for target input field. |
#### Title Display Mode
| Parameter | Value | Description |
| :-------- | :---- | :---------- |
| `web.text.title_mode` | `logo_only` | Show only logo, hide title and subtitle. |
| | `text_only` | Show only title and subtitle, hide logo. |
| | `logo_subtitle` | Show logo and subtitle, hide title. |
| | `all` | Show logo, title, and subtitle. |
#### Hostname Resolution Text
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `web.text.fqdn_tooltip` | String | `Use {protocol}` | Tooltip for hostname resolution buttons. `{protocol}` shows IPv4/IPv6. |
| `web.text.fqdn_message` | String | `Your browser has resolved {fqdn} to` | Message shown during hostname resolution. |
| `web.text.fqdn_error` | String | `Unable to resolve {fqdn}` | Error message for failed hostname resolution. |
| `web.text.fqdn_error_button` | String | `Try Again` | Button text for retrying hostname resolution. |
#### "My IP" Feature Text
<Callout type="info">
The "My IP" button automatically detects the user's public IP address and populates it as the query target. This is useful for users who want to test routing or connectivity to their own location.
</Callout>
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `web.text.ip_button` | String | `My IP` | Text for the IP detection button. |
| `web.text.ip_select` | String | `Select an IP Address` | Prompt for IP address selection. |
| `web.text.ip_error` | String | `Unable to determine IP Address` | Error when IP detection fails. |
| `web.text.no_ip` | String | `No {protocol} Address` | Message when specific IP version unavailable. |
#### Results and Status Text
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `web.text.cache_prefix` | String | `Results cached for ` | Prefix for cache countdown timer. |
| `web.text.cache_icon` | String | `Cached from {time} UTC` | Tooltip for cached result indicator. |
| `web.text.complete_time` | String | `Completed in {seconds}` | Tooltip showing query completion time. |
#### BGP/RPKI Status Text
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `web.text.rpki_valid` | String | `Valid` | Text for RPKI valid routes. |
| `web.text.rpki_invalid` | String | `Invalid` | Text for RPKI invalid routes. |
| `web.text.rpki_unknown` | String | `No ROAs Exist` | Text for RPKI unknown routes. |
| `web.text.rpki_unverified` | String | `Not Verified` | Text for RPKI unverified routes. |
| `web.text.no_communities` | String | `No Communities` | Text when route has no BGP communities. |
#### Example: Complete Text Customization
```yaml filename="config.yaml"
web:
text:
title_mode: "all"
title: "Network Operations Center"
subtitle: "AS65000 Looking Glass"
# Customize form labels
query_location: "Router Location"
query_type: "Diagnostic Type"
query_target: "Destination"
# Customize "My IP" feature
ip_button: "Detect My IP"
ip_select: "Choose your IP address"
# Customize hostname resolution
fqdn_message: "We found these IP addresses for {fqdn}"
fqdn_error: "Could not resolve hostname {fqdn}"
# Customize status indicators
cache_prefix: "Cached result expires in "
rpki_valid: "✓ Valid ROA"
rpki_invalid: "✗ Invalid ROA"
```
### Footer Links
Add custom links to the footer for documentation, policies, or external resources.
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `web.links[].title` | String | | Link text displayed to users. |
| `web.links[].url` | URL | | Destination URL. Can use `{primary_asn}` placeholder. |
| `web.links[].show_icon` | Boolean | `true` | Show external link icon. |
| `web.links[].side` | String | `left` | Footer side: `left` or `right`. |
| `web.links[].order` | Integer | `0` | Display order (lower numbers first). |
#### Example: Footer Links
```yaml filename="config.yaml"
web:
links:
# Default PeeringDB link (uses primary_asn automatically)
- title: "PeeringDB"
url: "https://www.peeringdb.com/asn/{primary_asn}"
side: "right"
order: 1
# Company website
- title: "Our Website"
url: "https://acmenetworks.com"
show_icon: false
side: "left"
order: 0
# Network status page
- title: "Network Status"
url: "https://status.acmenetworks.com"
side: "right"
order: 2
```
### Footer Menus
Add dropdown menus in the footer for longer content like terms of service or help documentation.
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `web.menus[].title` | String | | Menu title shown to users. |
| `web.menus[].content` | String | | Menu content (markdown supported) or path to file. |
| `web.menus[].side` | String | `left` | Footer side: `left` or `right`. |
| `web.menus[].order` | Integer | `0` | Display order (lower numbers first). |
<Callout type="info">
For the `content` field, you can either provide the content directly in YAML (for short text) or specify a path to a markdown file (for longer content). Hyperglass automatically detects file paths and loads the content.
</Callout>
#### Example: Footer Menus
```yaml filename="config.yaml"
web:
menus:
# Load terms from external file
- title: "Terms of Service"
content: "/etc/hyperglass/legal/terms.md"
side: "left"
order: 0
# Inline help content
- title: "Help"
content: |
## How to use this looking glass
1. Select a router location
2. Choose your query type (ping, traceroute, etc.)
3. Enter an IP address or hostname
4. Click Submit
For technical support, email network@example.com
side: "right"
order: 0
```
### Theme Customization
Customize colors, fonts, and appearance of the web interface.
#### Colors
You can customize both functional and palette colors:
**Palette Colors:**
```yaml filename="config.yaml"
web:
theme:
colors:
# Basic colors
black: "#000000"
white: "#ffffff"
dark: "#010101"
light: "#f5f6f7"
gray: "#c1c7cc"
# Brand colors
red: "#d84b4b"
orange: "#ff6b35"
yellow: "#edae49"
green: "#35b246"
blue: "#314cb6"
teal: "#35b299"
cyan: "#118ab2"
pink: "#f2607d"
purple: "#8d30b5"
```
**Functional Colors:**
```yaml filename="config.yaml"
web:
theme:
colors:
# Main brand colors
primary: "#118ab2" # Main interactive elements
secondary: "#35b299" # Secondary elements
# Status colors
success: "#35b246" # Success states
warning: "#edae49" # Warning states
error: "#d84b4b" # Error states
danger: "#d84b4b" # Danger states
```
#### Fonts
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `web.theme.fonts.body` | String | `Nunito` | Font family for body text. |
| `web.theme.fonts.mono` | String | `Fira Code` | Font family for monospace text (IPs, commands, etc.). |
#### Default Color Mode
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `web.theme.default_color_mode` | String | | Default theme: `light` or `dark`. If not set, uses system preference. |
#### Example: Complete Theme Customization
```yaml filename="config.yaml"
web:
theme:
default_color_mode: "dark"
colors:
# Corporate brand colors
primary: "#1e3a8a" # Corporate blue
secondary: "#059669" # Corporate green
# Custom palette
blue: "#1e40af"
green: "#047857"
red: "#dc2626"
fonts:
body: "Inter" # Modern sans-serif
mono: "JetBrains Mono" # Developer-friendly monospace
```
### Output Highlighting
Highlight specific patterns in query results for better visibility.
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `web.highlight[].pattern` | String | | Regular expression pattern to match. |
| `web.highlight[].label` | String | | Optional label for the highlight rule. |
| `web.highlight[].color` | String | `primary` | Theme color to use for highlighting. |
#### Example: Output Highlighting
```yaml filename="config.yaml"
web:
highlight:
# Highlight your own ASN in BGP paths
- pattern: "65000"
label: "Our ASN"
color: "primary"
# Highlight private IP ranges
- pattern: "192\.168\.\d+\.\d+"
label: "RFC 1918"
color: "warning"
# Highlight packet loss
- pattern: "\d+% loss"
label: "Packet Loss"
color: "error"
```
### Developer Credit
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `web.credit.enable` | Boolean | `true` | Show hyperglass developer credit in footer. |
<Callout emoji="❤️" type="info">
**Note from the Developer**
If your organization's policy allows, please consider keeping the developer credit enabled. The goal of this project is to get more networks using looking glasses to make all our lives easier. Since it's primarily other network operators who will use your looking glass, it helps them know where they can get their own.
</Callout>
---
## Complete Example Configuration
Here's a comprehensive example showing how all these options work together:
```yaml filename="config.yaml"
# Basic site information
site_title: "ACME Networks Looking Glass"
org_name: "ACME Networks Inc."
site_description: "Network diagnostic tools for ACME Networks AS65000"
primary_asn: 65000
# System settings
request_timeout: 120
fake_output: false
cors_origins:
- "https://network-tools.acmenetworks.com"
# Performance settings
cache:
timeout: 300
show_text: true
# API documentation
docs:
enable: true
base_url: "https://lg.acmenetworks.com"
title: "ACME Networks Looking Glass API"
description: "RESTful API for network diagnostic queries"
# Logging and notifications
logging:
directory: "/var/log/hyperglass"
format: "json"
max_size: "100MB"
# Send notifications to Slack
http:
enable: true
provider: "slack"
host: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
# Custom error messages
messages:
no_input: "Please specify a {field} for your query."
target_not_allowed: "Sorry, {target} is not permitted by our policy."
request_timeout: "Your request took too long and was cancelled."
# Structured data processing
structured:
communities:
mode: "name"
names:
"65000:100": "Customer Routes"
"65000:200": "Peer Routes"
"65000:999": "Blackhole"
rpki:
mode: "external"
backend: "cloudflare"
# Web interface customization
web:
# DNS resolution
dns_provider:
name: "cloudflare"
# Custom branding
logo:
light: "/etc/hyperglass/images/company-logo-light.svg"
dark: "/etc/hyperglass/images/company-logo-dark.svg"
width: "200px"
# Welcome message
greeting:
enable: true
title: "Terms of Service"
file: "/etc/hyperglass/legal/terms.md"
required: true
# Interface text
text:
title_mode: "all"
title: "Network Operations Center"
subtitle: "AS65000 Looking Glass"
query_location: "Router Location"
ip_button: "Detect My IP"
# Footer links
links:
- title: "PeeringDB"
url: "https://www.peeringdb.com/asn/{primary_asn}"
side: "right"
- title: "Network Status"
url: "https://status.acmenetworks.com"
side: "right"
# Footer menus
menus:
- title: "Help"
content: "/etc/hyperglass/help/user-guide.md"
side: "left"
# Theme customization
theme:
default_color_mode: "dark"
colors:
primary: "#1e3a8a"
secondary: "#059669"
fonts:
body: "Inter"
mono: "JetBrains Mono"
# Highlight patterns
highlight:
- pattern: "65000"
label: "Our ASN"
color: "primary"
- pattern: "\d+% loss"
label: "Packet Loss"
color: "error"
# Developer credit
credit:
enable: true
```
---
## Next Steps
<DocsButton href="/configuration/devices">
**Configure Devices** - Set up routers and network devices
</DocsButton>
<DocsButton href="/configuration/directives">
**Configure Directives** - Define available query types
</DocsButton>
<DocsButton href="/configuration/examples">
**See Examples** - View real-world configuration examples
</DocsButton>

4
docs/pages/configuration/examples/_meta.tsx
View file

@ -1,4 +1,8 @@
export default {
"quick-start": "Quick Start Examples",
"---": {
type: "separator",
},
"basic-configuration": "Basic Configuration",
"add-your-own-command": "Add Your Own Command",
"customize-the-ui": "Customize the UI",

453
docs/pages/configuration/examples/quick-start.mdx Normal file
View file

@ -0,0 +1,453 @@
---
title: Quick Start Configuration Examples
description: Common configuration patterns and examples to get started quickly
---
import { Callout } from 'nextra/components'
# Quick Start Configuration Examples
Here are the most common configuration patterns to get you started with hyperglass quickly. For complete documentation, see the [Complete Configuration Reference](/configuration/config/complete-config).
## Minimal Configuration
The absolute minimum configuration needed:
```yaml filename="config.yaml"
site_title: "My Network Looking Glass"
org_name: "My Company"
primary_asn: 65000
```
## Basic Corporate Setup
A typical corporate setup with branding and terms of service:
```yaml filename="config.yaml"
# Basic info
site_title: "ACME Networks Looking Glass"
org_name: "ACME Networks Inc."
primary_asn: 65000
site_description: "Network diagnostic tools for ACME Networks"
# Performance
request_timeout: 120
cache:
timeout: 300 # 5 minutes
# Web interface
web:
# Custom branding
logo:
light: "/etc/hyperglass/images/company-logo-light.svg"
dark: "/etc/hyperglass/images/company-logo-dark.svg"
# Welcome message with terms
greeting:
enable: true
title: "Terms of Service"
file: "/etc/hyperglass/terms.md"
required: true
button: "I Agree"
# Interface customization
text:
title: "Network Operations Center"
subtitle: "AS65000 Looking Glass"
# Footer links
links:
- title: "Company Website"
url: "https://acmenetworks.com"
show_icon: false
side: "left"
- title: "Network Status"
url: "https://status.acmenetworks.com"
side: "right"
```
## Privacy-Focused Setup
Emphasizing user privacy and security:
```yaml filename="config.yaml"
site_title: "Privacy-First Looking Glass"
org_name: "SecureNet"
primary_asn: 65001
web:
# Use privacy-focused DNS
dns_provider:
name: "cloudflare" # More privacy-focused than Google
# Informative text about privacy
text:
ip_button: "Detect My IP (Private)"
fqdn_message: "Securely resolved {fqdn} to"
# Privacy-focused greeting
greeting:
enable: true
title: "Your Privacy Matters"
content: |
## Privacy Notice
- DNS queries use encrypted DNS-over-HTTPS
- Your IP detection happens in your browser
- We don't log sensitive query details
- All connections use HTTPS encryption
required: false
button: "I Understand"
# Minimal logging
logging:
format: "text"
# No HTTP webhooks for privacy
```
## High-Performance Setup
Optimized for performance with extended caching:
```yaml filename="config.yaml"
site_title: "High-Performance Looking Glass"
org_name: "FastNet ISP"
primary_asn: 65002
# Performance optimizations
request_timeout: 60 # Faster timeouts
cache:
timeout: 600 # Cache for 10 minutes
show_text: true # Show cache status
web:
# Optimized text
text:
cache_prefix: "Cached result expires in "
complete_time: "⚡ Completed in {seconds}"
# Performance theme
theme:
colors:
primary: "#059669" # Fast green
secondary: "#0ea5e9" # Speed blue
default_color_mode: "dark" # Easier on eyes
# Structured output for faster parsing
structured:
rpki:
mode: "external"
backend: "cloudflare" # Fast RPKI validation
```
## ISP/Service Provider Setup
Configuration for internet service providers:
```yaml filename="config.yaml"
site_title: "GlobalNet Looking Glass"
org_name: "GlobalNet Internet Services"
primary_asn: 64500
site_description: "Network diagnostics for GlobalNet AS64500 customers and peers"
web:
# Professional branding
logo:
light: "/etc/hyperglass/branding/globalnet-light.svg"
dark: "/etc/hyperglass/branding/globalnet-dark.svg"
width: "250px"
# Comprehensive footer
links:
- title: "PeeringDB"
url: "https://www.peeringdb.com/asn/{primary_asn}"
side: "right"
order: 1
- title: "Peering Policy"
url: "https://globalnet.com/peering"
side: "right"
order: 2
- title: "Customer Portal"
url: "https://portal.globalnet.com"
side: "left"
order: 1
- title: "Network Status"
url: "https://status.globalnet.com"
side: "left"
order: 2
menus:
- title: "Peering Information"
content: |
## Peering with GlobalNet
- **ASN**: AS64500
- **IPv4 Prefix**: 203.0.113.0/24
- **IPv6 Prefix**: 2001:db8::/32
- **NOC**: noc@globalnet.com
- **Peering**: peering@globalnet.com
We maintain an open peering policy and welcome new peers.
side: "right"
# ISP-focused text
text:
title: "Network Operations Center"
subtitle: "Peering & Transit Services"
query_location: "Point of Presence"
# BGP-focused structured output
structured:
communities:
mode: "name"
names:
"64500:100": "Customer Routes"
"64500:200": "Peer Routes"
"64500:300": "Transit Routes"
"64500:400": "Internal Routes"
"64500:666": "Blackhole"
"64500:777": "No Export"
rpki:
mode: "external"
backend: "cloudflare"
# Comprehensive API docs for automation
docs:
enable: true
title: "GlobalNet Looking Glass API"
description: "Programmatic access to network diagnostic tools"
base_url: "https://lg.globalnet.com"
```
## Enterprise Internal Setup
For internal corporate networks:
```yaml filename="config.yaml"
site_title: "ACME Internal Network Tools"
org_name: "ACME Corporation"
primary_asn: 65000
web:
# Internal-focused interface
text:
title_mode: "all"
title: "IT Network Diagnostics"
subtitle: "Internal Use Only"
query_location: "Network Segment"
ip_button: "My Internal IP"
# Corporate theme
theme:
colors:
primary: "#1e40af" # Corporate blue
secondary: "#059669" # Corporate green
fonts:
body: "Inter"
mono: "JetBrains Mono"
# Internal policies
greeting:
enable: true
title: "IT Policy Reminder"
content: |
## Network Diagnostic Tools
These tools are for authorized IT personnel only.
- Use responsibly and only for legitimate troubleshooting
- Do not test external targets without approval
- Report any suspicious network activity
- Contact IT Security for questions: security@acme.com
required: true
button: "I Acknowledge"
links:
- title: "IT Helpdesk"
url: "https://helpdesk.acme.local"
side: "left"
- title: "Network Documentation"
url: "https://wiki.acme.local/network"
side: "left"
# Detailed logging for internal audit
logging:
directory: "/var/log/hyperglass"
format: "json"
max_size: "200MB"
# Log to internal SIEM
http:
enable: true
provider: "generic"
host: "https://siem.acme.local/api/logs"
authentication:
mode: "api_key"
password: "your-siem-api-key"
header: "X-API-Key"
```
## Development/Testing Setup
For development and testing environments:
```yaml filename="config.yaml"
site_title: "Development Looking Glass"
org_name: "DevNet Testing"
primary_asn: 65999
# Development settings
fake_output: true # Use fake data for testing
request_timeout: 30 # Shorter timeouts for dev
cors_origins: # Allow local development
- "http://localhost:3000"
- "http://127.0.0.1:3000"
cache:
timeout: 30 # Short cache for testing
show_text: true
web:
# Development theme
theme:
default_color_mode: "dark"
colors:
primary: "#f59e0b" # Warning amber for dev
secondary: "#8b5cf6" # Purple for distinction
# Development notices
text:
title: "🔧 Development Environment"
subtitle: "Testing & Development Only"
greeting:
enable: true
title: "Development Environment"
content: |
## ⚠️ Development Environment
This is a development/testing instance of hyperglass.
- Data may be fake or simulated
- Configuration changes frequently
- Not suitable for production use
- Contact developers: dev@example.com
required: false
button: "Continue to Testing"
# Extensive logging for debugging
logging:
format: "json"
directory: "/tmp/hyperglass-dev"
# Enable all structured features for testing
structured:
communities:
mode: "name"
names:
"65999:1": "Test Community 1"
"65999:2": "Test Community 2"
rpki:
mode: "external"
backend: "cloudflare"
# Full API documentation for testing
docs:
enable: true
title: "Development API Docs"
description: "API documentation for testing and development"
```
## Monitoring Integration
With comprehensive monitoring and alerting:
```yaml filename="config.yaml"
site_title: "MonitorNet Looking Glass"
org_name: "MonitorNet Services"
primary_asn: 65100
# Monitoring-optimized settings
cache:
timeout: 180 # 3 minutes for monitoring
show_text: true
logging:
directory: "/var/log/hyperglass"
format: "json" # Structured logs for monitoring
max_size: "500MB"
# Multiple monitoring integrations
http:
enable: true
provider: "slack"
host: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
timeout: 5.0
# Custom headers for monitoring context
headers:
"X-Environment": "production"
"X-Service": "hyperglass"
web:
# Monitoring-friendly highlighting
highlight:
- pattern: "100% loss"
label: "Total Packet Loss"
color: "error"
- pattern: "[5-9][0-9]% loss"
label: "High Packet Loss"
color: "warning"
- pattern: "timeout"
label: "Timeout"
color: "error"
- pattern: "65100"
label: "Our Network"
color: "primary"
text:
complete_time: "⏱ Query time: {seconds}"
cache_prefix: "📊 Cached for "
rpki_invalid: "❌ RPKI Invalid"
rpki_valid: "✅ RPKI Valid"
# Detailed structured output for monitoring
structured:
communities:
mode: "name"
names:
"65100:911": "🚨 Emergency Routes"
"65100:999": "🚫 Blackhole"
rpki:
mode: "external"
backend: "cloudflare"
```
---
<Callout type="info">
**Next Steps**: Once you have a basic configuration working, see the [Complete Configuration Reference](/configuration/config/complete-config) for all available options and detailed examples.
</Callout>
## Configuration File Location
Place your `config.yaml` file in the hyperglass configuration directory:
- **Docker**: Mount to `/etc/hyperglass/config.yaml`
- **System Install**: `/etc/hyperglass/config.yaml`
- **Development**: `./config.yaml` in your project directory
## Validation
After creating your configuration, validate it with:
```bash
# Check configuration syntax
hyperglass --validate-config
# Test with fake output
hyperglass --fake-output
# Full startup test
hyperglass --debug
```

362
docs/pages/user-guide.mdx Normal file
View file

@ -0,0 +1,362 @@
---
title: User Guide
description: How to use the hyperglass web interface
---
import { Callout } from 'nextra/components'
# User Guide
This guide explains how to use the hyperglass web interface from an end-user perspective. If you're looking to configure hyperglass as an administrator, see the [Configuration Guide](/configuration).
## Getting Started
The hyperglass web interface provides an easy-to-use form for performing network diagnostics. Here's how to use it:
### 1. Select a Location
Choose which router/location you want to query from using the location selector. This determines which network device will execute your diagnostic command.
- **Dropdown Mode**: Select from a list of available locations
- **Gallery Mode**: Choose from a visual grid of location cards (used when there are 5 or fewer locations)
### 2. Choose Query Type
Select the type of network diagnostic you want to perform:
- **Ping**: Test basic connectivity and measure round-trip time
- **Traceroute**: Show the network path to a destination
- **BGP Route**: Look up BGP routing information for an IP prefix
- **BGP Community**: Find routes with specific BGP communities
- **BGP AS Path**: Find routes traversing specific ASNs
### 3. Enter Your Target
Specify what you want to query. This can be:
- **IP Address**: `8.8.8.8` or `2001:4860:4860::8888`
- **Hostname**: `google.com` or `www.example.com`
- **IP Prefix**: `8.8.8.0/24` (for BGP queries)
- **AS Number**: `AS15169` (for AS path queries)
## Using Hostnames (FQDN Resolution)
<Callout type="info">
When you enter a hostname like `google.com` instead of an IP address, hyperglass automatically resolves it to IP addresses using secure DNS-over-HTTPS. This happens directly in your browser for privacy and security.
</Callout>
### How Hostname Resolution Works
1. **Enter a hostname**: Type something like `google.com` in the target field
2. **Detection**: hyperglass detects this is a hostname (not an IP address)
3. **DNS Resolution**: A modal opens showing "Resolving hostname..."
4. **Choose IP**: Select from available IPv4 and/or IPv6 addresses
5. **Submit Query**: The selected IP address is used for your diagnostic query
### Hostname Resolution Features
- **IPv4 and IPv6**: Get both A and AAAA records when available
- **Privacy-Focused**: Uses DNS-over-HTTPS (encrypted) instead of plain DNS
- **Multiple Providers**: Supports Cloudflare DNS, Google DNS, or custom resolvers
- **Browser-Based**: Resolution happens in your browser, not on the server
### Example: Resolving a Hostname
```
1. Enter "google.com" as your target
2. Click Submit
3. See resolution modal:
┌─────────────────────────────────────┐
│ Your browser has resolved google.com to │
│ │
│ [→] 142.250.191.14 (IPv4) │
│ [→] 2607:f8b0:4004:c1b::71 (IPv6) │
│ │
└─────────────────────────────────────┘
4. Click your preferred IP address
5. Query executes using the selected IP
```
## Using "My IP" Feature
<Callout type="info">
The "My IP" button automatically detects your public IP address and uses it as the query target. This is useful for testing connectivity or routing to your current location.
</Callout>
### How "My IP" Works
1. **Click the "My IP" button** (located next to the target input field)
2. **IP Detection**: A modal opens showing "Detecting your IP address..."
3. **Choose Version**: Select your IPv4 or IPv6 address (or both if available)
4. **Auto-Population**: Your selected IP is automatically entered as the target
### When to Use "My IP"
- **Connectivity Testing**: Check if the network can reach your location
- **Routing Analysis**: See what path traffic takes to reach you
- **Latency Testing**: Measure round-trip time to your connection
- **Troubleshooting**: Diagnose connectivity issues from your current network
### Example: Using My IP
```
1. Click the "My IP" button
2. See detection modal:
┌─────────────────────────────────────┐
│ Select an IP Address │
│ │
│ [→] 203.0.113.45 (IPv4) │
│ [→] 2001:db8::1 (IPv6) │
│ │
└─────────────────────────────────────┘
3. Click your preferred IP version
4. IP is automatically entered as target
5. Submit your query as normal
```
## Query Types Explained
### Ping
Tests basic connectivity and measures round-trip time.
**Use Cases:**
- Check if a host is reachable
- Measure network latency
- Basic connectivity troubleshooting
**Sample Output:**
```
PING google.com (142.250.191.14): 56 data bytes
64 bytes from 142.250.191.14: icmp_seq=0 ttl=58 time=12.345 ms
64 bytes from 142.250.191.14: icmp_seq=1 ttl=58 time=11.678 ms
--- google.com ping statistics ---
2 packets transmitted, 2 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 11.678/12.012/12.345/0.334 ms
```
### Traceroute
Shows the network path packets take to reach a destination.
**Use Cases:**
- Identify network routing paths
- Find where connectivity breaks
- Analyze routing decisions
- Network troubleshooting
**Sample Output:**
```
traceroute to google.com (142.250.191.14), 30 hops max, 60 byte packets
1 gateway.local (192.168.1.1) 1.234 ms 1.456 ms 1.789 ms
2 isp-router.net (203.0.113.1) 5.123 ms 5.234 ms 5.345 ms
3 backbone.net (198.51.100.1) 12.34 ms 12.45 ms 12.56 ms
4 google-peer.net (142.250.191.14) 15.67 ms 15.78 ms 15.89 ms
```
### BGP Route
Look up BGP routing information for IP prefixes.
**Use Cases:**
- Check BGP route advertisements
- Verify RPKI validation status
- Analyze AS paths and communities
- Route troubleshooting
**Sample Output:**
```
BGP routing table entry for 8.8.8.0/24
Paths: 1 available
15169
192.0.2.1 from 192.0.2.1
Origin IGP, metric 0, valid, external, best
Community: 65000:100 65000:200
RPKI validation state: Valid
Last update: 2 hours ago
```
### BGP Community
Find routes with specific BGP communities.
**Use Cases:**
- Filter routes by community values
- Analyze traffic engineering policies
- Debug community-based routing
### BGP AS Path
Find routes traversing specific Autonomous Systems.
**Use Cases:**
- Analyze internet routing paths
- Check AS-level connectivity
- Investigate routing policies
## Understanding Results
### Status Indicators
Results include several status indicators:
- **✓ Success**: Query completed successfully
- **⚠ Warning**: Query completed with warnings
- **✗ Error**: Query failed
- **🕒 Cached**: Result was served from cache
- **⏱ Time**: Shows how long the query took
### Cache Information
<Callout type="info">
To improve performance, hyperglass caches query results. Cached results are marked with a clock icon and show when they expire. Fresh queries are automatically run when cache expires.
</Callout>
When you see cached results:
- **Cache Timer**: Shows "Results cached for X seconds"
- **Cache Icon**: Hover to see when the original query was run
- **Auto-Refresh**: New query runs automatically when cache expires
### RPKI Validation
For BGP queries, routes show RPKI validation status:
- **Valid**: Route has valid ROA (Route Origin Authorization)
- **Invalid**: Route conflicts with ROA
- **Unknown**: No ROA exists for this route
- **Not Verified**: RPKI validation not performed
## Common Use Cases
### Network Troubleshooting
**Scenario**: Website seems slow from your location
1. Use **"My IP"** feature to get your IP address
2. Run **ping** to measure basic connectivity and latency
3. Run **traceroute** to see the network path
4. Check **BGP route** to verify optimal routing
### Connectivity Testing
**Scenario**: Check if a server is reachable
1. Enter the server's **hostname or IP address**
2. Select multiple **router locations** to test from different points
3. Use **ping** for basic reachability
4. Use **traceroute** if ping fails to find where connectivity breaks
### Routing Analysis
**Scenario**: Analyze how traffic reaches a destination
1. Enter the **destination IP or prefix**
2. Use **BGP route** to see routing table entries
3. Check **AS path** to understand routing decisions
4. Verify **RPKI validation** for security
### Multi-Location Testing
**Scenario**: Test connectivity from multiple network locations
1. Choose your **target** (IP, hostname, or prefix)
2. Select **multiple locations** using Ctrl+Click (or Cmd+Click on Mac)
3. Submit query to test from **all selected locations simultaneously**
4. Compare results to identify location-specific issues
## Tips and Best Practices
### Efficient Querying
- **Use hostnames** when you don't know IP addresses - hyperglass will resolve them
- **Try "My IP"** for connectivity testing from your location
- **Select multiple locations** to get a broader view of network behavior
- **Check cached results** first - they may already have the information you need
### Interpreting Results
- **Compare multiple locations** to identify regional issues
- **Look at RPKI status** for BGP routes to verify security
- **Check AS paths** to understand routing decisions
- **Use traceroute** when ping shows connectivity issues
### Privacy and Security
- **DNS resolution** uses encrypted DNS-over-HTTPS for privacy
- **No logging** of sensitive query details in most configurations
- **RPKI validation** helps verify route authenticity
- **Rate limiting** prevents abuse while allowing legitimate use
## Troubleshooting
### Common Issues
**"Unable to resolve hostname"**
- Check spelling of the hostname
- Try a different DNS provider in browser settings
- Use an IP address instead
**"Request timed out"**
- Target may be unreachable or filtering responses
- Try a different query type
- Check from multiple locations
**"No output"**
- Query completed but returned no results
- Target may not exist in routing tables
- Try a broader search (e.g., larger prefix)
**"Target not allowed"**
- Query target is blocked by policy
- Contact administrator if you believe this is an error
- Try a different target
### Getting Help
If you encounter issues:
1. **Check multiple locations** - issue may be location-specific
2. **Try different query types** - some may work when others don't
3. **Contact network administrators** - they can review logs and policies
4. **Report persistent issues** - help improve the service
---
## Advanced Features
### Keyboard Shortcuts
- **Enter**: Submit query
- **Ctrl/Cmd + Click**: Select multiple locations
- **Tab**: Navigate between form fields
- **Escape**: Close modals/popups
### URL Parameters
You can bookmark or share queries using URL parameters:
```
https://lg.example.com/?location=router1&type=ping&target=8.8.8.8
```
Parameters:
- `location`: Router location ID
- `type`: Query type (ping, traceroute, bgp_route, etc.)
- `target`: Query target (IP, hostname, prefix, etc.)
### API Access
For programmatic access, use the REST API:
```bash
curl -X POST https://lg.example.com/api/query \
-H "Content-Type: application/json" \
-d '{
"query_location": "router1",
"query_type": "ping",
"query_target": "8.8.8.8"
}'
```
See the [API Documentation](/api/docs) for complete details.