170 lines
16 KiB
HTML
170 lines
16 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>Help & User Guide</title>
|
|
<link rel="icon" type="image/png" href="{{ LOGO_PNG }}">
|
|
<link href="/static/css/output.css" rel="stylesheet">
|
|
<link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css" rel="stylesheet">
|
|
</head>
|
|
<body class="bg-gray-300 text-gray-900 dark:bg-zinc-900 dark:text-gray-100 min-h-screen flex flex-col">
|
|
{% include 'header.html' %}
|
|
<div class="flex-1 flex items-center justify-center mx-4">
|
|
<div class="container py-8 max-w-2xl pt-20">
|
|
<h1 class="text-3xl font-bold mb-8 text-center">Help & User Guide</h1>
|
|
<div class="space-y-10 text-lg">
|
|
<div class="bg-gray-200 dark:bg-zinc-800 rounded-2xl shadow-lg p-8">
|
|
<h2 class="text-2xl font-semibold mb-4 border-b border-gray-700 pb-2">Subnets & Devices</h2>
|
|
<div class="space-y-4">
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Managing Subnets</h3>
|
|
<p>To add or edit subnets, go to the <a href="/admin" class="text-blue-600 dark:text-blue-400 hover:underline">Admin</a> page. Click <span class="bg-gray-300 dark:bg-zinc-700 px-2 py-1 rounded">Add Subnet</span> to create a new subnet, or use the edit button to modify existing subnets. Subnets are associated with sites and can be organised by location.</p>
|
|
</div>
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Adding a Device</h3>
|
|
<p>To add a device, visit the <a href="/devices" class="text-blue-600 dark:text-blue-400 hover:underline">Devices</a> page and click <span class="bg-gray-300 dark:bg-zinc-700 px-2 py-1 rounded">Add Device</span>.</p>
|
|
</div>
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Assigning IP Addresses</h3>
|
|
<p>To assign an IP address, you must first add a device. Then, from the <a href="/devices" class="text-blue-600 dark:text-blue-400 hover:underline">Devices</a> page, click on a device to view its details and use the <span class="bg-gray-300 dark:bg-zinc-700 px-2 py-1 rounded">Add IP</span> option to assign an IP address from a subnet.</p>
|
|
</div>
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Viewing and Editing Devices</h3>
|
|
<p>Click on any device in the <a href="/devices" class="text-blue-600 dark:text-blue-400 hover:underline">Devices</a> list to view or edit its details, including assigned IPs, device types and a description where necessary.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="bg-gray-200 dark:bg-zinc-800 rounded-2xl shadow-lg p-8">
|
|
<h2 class="text-2xl font-semibold mb-4 border-b border-gray-700 pb-2">Racks</h2>
|
|
<div class="space-y-4">
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Adding a Rack</h3>
|
|
<p>To add a new rack, go to the <a href="/racks" class="text-blue-600 dark:text-blue-400 hover:underline">Racks</a> page and click the <span class="bg-gray-300 dark:bg-zinc-700 px-2 py-1 rounded">Add Rack</span> button. Fill in the details and submit the form.</p>
|
|
</div>
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Assigning Devices to Racks</h3>
|
|
<p>After adding a device, you can assign it to a rack from the <a href="/racks" class="text-blue-600 dark:text-blue-400 hover:underline">Rack</a> details page. Click on a rack from the <a href="/racks" class="text-blue-600 dark:text-blue-400 hover:underline">Racks</a> page, then use the options to add or remove devices within the rack.</p>
|
|
</div>
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Non-Networked Devices</h3>
|
|
<p>Racks can also contain non-networked devices (such as shelves, patch panels, or other equipment that does not require an IP address). To add a non-networked device, go to a rack details page and use the option to add a device by name without assigning an IP address. These devices will appear in the rack layout but will not be listed on the Devices page.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="bg-gray-200 dark:bg-zinc-800 rounded-2xl shadow-lg p-8">
|
|
<h2 class="text-2xl font-semibold mb-4 border-b border-gray-700 pb-2">User Management & Audit</h2>
|
|
<div class="space-y-4">
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">User & Role Management</h3>
|
|
<p>Administrators can manage users and roles from the <a href="/users" class="text-blue-600 dark:text-blue-400 hover:underline">Users</a> page. This includes creating users, assigning roles, and managing custom roles with specific permission sets. Only users with the appropriate permissions can access this page.</p>
|
|
</div>
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Understanding Roles</h3>
|
|
<p>The system uses role-based access control to manage what users can do. There are three default roles:</p>
|
|
<ul class="list-disc list-inside mt-2 space-y-1 ml-4">
|
|
<li><strong>Admin:</strong> Full access to all features including user and role management</li>
|
|
<li><strong>User:</strong> Can view and manage most features (devices, subnets, racks, etc.) but cannot manage users or roles</li>
|
|
<li><strong>View Only:</strong> Read-only access to view pages but cannot make any changes</li>
|
|
</ul>
|
|
</div>
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Custom Roles</h3>
|
|
<p>Administrators can create custom roles with specific permission sets. Go to the <a href="/users" class="text-blue-600 dark:text-blue-400 hover:underline">Users</a> page and click the "Roles & Permissions" tab to create and manage roles.</p>
|
|
</div>
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Permission Granularity</h3>
|
|
<p>Permissions are very granular, allowing fine-grained control over what each role can do. Permissions are organised into categories like View, Device Management, Network Management, Rack Management, and Administration.</p>
|
|
</div>
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Audit & History</h3>
|
|
<p>All changes are logged and can be reviewed on the <a href="/audit" class="text-blue-600 dark:text-blue-400 hover:underline">Audit</a> page for accountability and troubleshooting. The audit log shows who made changes, what was changed, and when.</p>
|
|
</div>
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">API Keys</h3>
|
|
<p>Each user has a unique API key that can be used to authenticate API requests. API keys can be viewed and regenerated from the <a href="/users" class="text-blue-600 dark:text-blue-400 hover:underline">Users</a> page. Keep your API key secure and never share it publicly.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="bg-gray-200 dark:bg-zinc-800 rounded-2xl shadow-lg p-8">
|
|
<h2 class="text-2xl font-semibold mb-4 border-b border-gray-700 pb-2">API Documentation</h2>
|
|
<div class="space-y-4">
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Authentication</h3>
|
|
<p>All API requests require authentication using an API key. You can provide the API key in one of three ways:</p>
|
|
<ul class="list-disc list-inside mt-2 space-y-1 ml-4">
|
|
<li><strong>Header:</strong> <code class="bg-gray-300 dark:bg-zinc-700 px-2 py-1 rounded text-sm">X-API-Key: your_api_key</code></li>
|
|
<li><strong>Authorization Header:</strong> <code class="bg-gray-300 dark:bg-zinc-700 px-2 py-1 rounded text-sm">Authorization: Bearer your_api_key</code></li>
|
|
<li><strong>Query Parameter:</strong> <code class="bg-gray-300 dark:bg-zinc-700 px-2 py-1 rounded text-sm">?api_key=your_api_key</code></li>
|
|
</ul>
|
|
</div>
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Base URL</h3>
|
|
<p>All API endpoints are prefixed with <code class="bg-gray-300 dark:bg-zinc-700 px-2 py-1 rounded text-sm">/api/v1</code></p>
|
|
</div>
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Available Endpoints</h3>
|
|
<div class="space-y-3 mt-2">
|
|
<div>
|
|
<h4 class="font-semibold">Devices</h4>
|
|
<ul class="list-disc list-inside ml-4 text-sm space-y-1">
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">GET /api/v1/devices</code> - List all devices</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">GET /api/v1/devices/{id}</code> - Get device details</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">POST /api/v1/devices</code> - Create device</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">PUT /api/v1/devices/{id}</code> - Update device</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">DELETE /api/v1/devices/{id}</code> - Delete device</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">POST /api/v1/devices/{id}/ips</code> - Add IP to device</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">DELETE /api/v1/devices/{id}/ips/{ip_id}</code> - Remove IP from device</li>
|
|
</ul>
|
|
</div>
|
|
<div>
|
|
<h4 class="font-semibold">Subnets</h4>
|
|
<ul class="list-disc list-inside ml-4 text-sm space-y-1">
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">GET /api/v1/subnets</code> - List all subnets</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">GET /api/v1/subnets/{id}</code> - Get subnet details</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">POST /api/v1/subnets</code> - Create subnet</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">PUT /api/v1/subnets/{id}</code> - Update subnet</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">DELETE /api/v1/subnets/{id}</code> - Delete subnet</li>
|
|
</ul>
|
|
</div>
|
|
<div>
|
|
<h4 class="font-semibold">Racks</h4>
|
|
<ul class="list-disc list-inside ml-4 text-sm space-y-1">
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">GET /api/v1/racks</code> - List all racks</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">GET /api/v1/racks/{id}</code> - Get rack details</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">POST /api/v1/racks</code> - Create rack</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">DELETE /api/v1/racks/{id}</code> - Delete rack</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">POST /api/v1/racks/{id}/devices</code> - Add device to rack</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">DELETE /api/v1/racks/{id}/devices/{rack_device_id}</code> - Remove device from rack</li>
|
|
</ul>
|
|
</div>
|
|
<div>
|
|
<h4 class="font-semibold">Other</h4>
|
|
<ul class="list-disc list-inside ml-4 text-sm space-y-1">
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">GET /api/v1/info</code> - Get API info and user details</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">GET /api/v1/device-types</code> - List device types</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">GET /api/v1/subnets/{id}/dhcp</code> - Get DHCP pools</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">POST /api/v1/subnets/{id}/dhcp</code> - Configure DHCP pools</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">GET /api/v1/audit</code> - Get audit log</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">GET /api/v1/users</code> - List users (admin only)</li>
|
|
<li><code class="bg-gray-300 dark:bg-zinc-700 px-1 rounded">GET /api/v1/roles</code> - List roles (admin only)</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Permissions</h3>
|
|
<p>API endpoints respect the same role-based permissions as the web interface. Users can only perform actions that their role allows. If a user lacks the required permission, the API will return a <code class="bg-gray-300 dark:bg-zinc-700 px-2 py-1 rounded text-sm">403 Forbidden</code> error.</p>
|
|
</div>
|
|
<div>
|
|
<h3 class="text-xl font-semibold mb-1">Response Format</h3>
|
|
<p>All API responses are in JSON format. Successful requests return <code class="bg-gray-300 dark:bg-zinc-700 px-2 py-1 rounded text-sm">200 OK</code> or <code class="bg-gray-300 dark:bg-zinc-700 px-2 py-1 rounded text-sm">201 Created</code> with the requested data. Errors return appropriate HTTP status codes with an error message in the response body.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|