0
# Nautobot
1
2
A comprehensive network source of truth and automation platform built as a Django web application. Nautobot serves as a flexible data platform that enables network infrastructure management through customizable data models, REST APIs, GraphQL interfaces, and Git integration. The platform supports an extensible plugin architecture for creating custom network automation applications, provides comprehensive data validation and relationship management, and offers features like webhooks, change logging, and role-based permissions.
3
4
## Package Information
5
6
- **Package Name**: nautobot
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install nautobot`
10
11
## Core Imports
12
13
```python
14
import nautobot
15
```
16
17
For Django setup (required before using any models or APIs):
18
19
```python
20
import nautobot
21
nautobot.setup() # Configure Django with Nautobot settings
22
```
23
24
For model imports:
25
26
```python
27
from nautobot.dcim.models import Device, Location, Interface
28
from nautobot.ipam.models import IPAddress, Prefix, VLAN
29
from nautobot.extras.models import Tag, Status, Role
30
```
31
32
For API usage:
33
34
```python
35
from nautobot.core.api.serializers import NautobotModelSerializer
36
from nautobot.dcim.api.views import DeviceViewSet
37
```
38
39
## Basic Usage
40
41
```python
42
import nautobot
43
nautobot.setup()
44
45
# Working with devices
46
from nautobot.dcim.models import Device, Location, DeviceType
47
48
# Get all devices
49
devices = Device.objects.all()
50
51
# Get devices at a specific location
52
location = Location.objects.get(name="Datacenter-1")
53
location_devices = Device.objects.filter(location=location)
54
55
# Create a new device
56
from nautobot.extras.models import Status
57
active_status = Status.objects.get(name="Active")
58
59
device = Device.objects.create(
60
name="router-01",
61
device_type=DeviceType.objects.get(model="ASR1001-X"),
62
location=location,
63
status=active_status
64
)
65
66
# Working with IP addresses
67
from nautobot.ipam.models import IPAddress, Namespace
68
69
# Create an IP address
70
namespace = Namespace.objects.get(name="Global")
71
ip = IPAddress.objects.create(
72
address="192.168.1.1/24",
73
namespace=namespace,
74
status=active_status
75
)
76
77
# Assign IP to device interface
78
from nautobot.dcim.models import Interface
79
interface = Interface.objects.get(device=device, name="GigabitEthernet0/0/0")
80
ip.assigned_object = interface
81
ip.save()
82
```
83
84
## Architecture
85
86
Nautobot follows a modular Django architecture with several key components:
87
88
- **Models**: Database schema and business logic organized by functional area (DCIM, IPAM, etc.)
89
- **APIs**: REST and GraphQL APIs providing full CRUD operations
90
- **Jobs**: Celery-based background task system for automation workflows
91
- **Plugins**: Extensible app architecture allowing custom functionality
92
- **UI**: Django-based web interface with customizable views and forms
93
- **Data Sources**: Git integration for configuration and data management
94
95
The plugin system enables third-party developers to extend Nautobot with custom models, APIs, views, and automation logic while maintaining compatibility with the core platform.
96
97
## Capabilities
98
99
### Core Framework
100
101
Core functionality including Django setup, base models, API infrastructure, form handling, job system, and plugin architecture. Provides the foundation for all other modules.
102
103
```python { .api }
104
def setup(config_path=None):
105
"""Configure Django with Nautobot settings."""
106
107
class BaseModel:
108
"""Abstract base model with UUID primary key, natural keys, and validation."""
109
110
class NautobotModelSerializer:
111
"""Main model serializer for API operations."""
112
113
class NautobotAppConfig:
114
"""Base app configuration class for plugins."""
115
```
116
117
[Core Framework](./core-framework.md)
118
119
### Device and Infrastructure Management (DCIM)
120
121
Physical and virtual network infrastructure management including devices, locations, racks, cables, power, and device components. Provides comprehensive modeling of network hardware and connectivity.
122
123
```python { .api }
124
class Device:
125
"""Physical network devices."""
126
127
class Location:
128
"""Physical locations/sites."""
129
130
class Interface:
131
"""Network interfaces on devices."""
132
133
class Cable:
134
"""Physical cable connections."""
135
```
136
137
[Device and Infrastructure Management](./dcim.md)
138
139
### IP Address Management (IPAM)
140
141
IP address space management including prefixes, IP addresses, VLANs, VRFs, namespaces, and routing. Supports hierarchical IP space organization and VLAN management.
142
143
```python { .api }
144
class IPAddress:
145
"""Individual IP addresses."""
146
147
class Prefix:
148
"""IP prefixes/networks."""
149
150
class VLAN:
151
"""Virtual LANs."""
152
153
class VRF:
154
"""Virtual routing and forwarding instances."""
155
```
156
157
[IP Address Management](./ipam.md)
158
159
### Extensibility and Automation
160
161
Advanced features including custom fields, relationships, jobs, webhooks, templates, secrets management, and configuration contexts. Enables customization and automation workflows.
162
163
```python { .api }
164
class Job:
165
"""Background job definitions."""
166
167
class CustomField:
168
"""Runtime-configurable custom fields."""
169
170
class Relationship:
171
"""Custom object relationships."""
172
173
class Webhook:
174
"""Webhook integrations."""
175
```
176
177
[Extensibility and Automation](./extensibility.md)
178
179
### Circuit Management
180
181
Service provider circuit management including circuits, providers, and circuit terminations. Manages external network connectivity and carrier services.
182
183
```python { .api }
184
class Circuit:
185
"""Service provider circuits."""
186
187
class Provider:
188
"""Service providers."""
189
190
class CircuitTermination:
191
"""Circuit endpoints."""
192
```
193
194
[Circuit Management](./circuits.md)
195
196
### Tenancy and User Management
197
198
Multi-tenancy support and user management including tenants, groups, permissions, and authentication. Provides role-based access control and organizational separation.
199
200
```python { .api }
201
class Tenant:
202
"""Tenant objects for multi-tenancy."""
203
204
class User:
205
"""Extended user model."""
206
207
class ObjectPermission:
208
"""Object-level permissions."""
209
```
210
211
[Tenancy and User Management](./tenancy-users.md)
212
213
### Virtualization and Cloud
214
215
Virtual infrastructure management including virtual machines, cloud services, and wireless networks. Extends the DCIM model to virtual and cloud environments.
216
217
```python { .api }
218
class VirtualMachine:
219
"""Virtual machines."""
220
221
class VMInterface:
222
"""Virtual machine interfaces."""
223
```
224
225
[Virtualization and Cloud](./virtualization-cloud.md)
226
227
## Installation and Setup
228
229
```python
230
# Install Nautobot
231
pip install nautobot
232
233
# Basic setup in your application
234
import nautobot
235
nautobot.setup() # Must be called before using models or APIs
236
237
# Access the version
238
print(nautobot.__version__) # "2.4.17"
239
```
240
241
## Configuration
242
243
Nautobot requires Django configuration. The `setup()` function handles this automatically:
244
245
```python
246
import nautobot
247
248
# Use default configuration path
249
nautobot.setup()
250
251
# Or specify custom configuration
252
nautobot.setup(config_path="/path/to/nautobot_config.py")
253
```
254
255
## Common Patterns
256
257
**Model Access:**
258
```python
259
from nautobot.dcim.models import Device
260
devices = Device.objects.filter(status__name="Active")
261
```
262
263
**API Usage:**
264
```python
265
from nautobot.dcim.api.serializers import DeviceSerializer
266
from nautobot.dcim.models import Device
267
268
device = Device.objects.first()
269
serializer = DeviceSerializer(device)
270
data = serializer.data
271
```
272
273
**Custom Fields:**
274
```python
275
from nautobot.extras.models import CustomField
276
custom_field = CustomField.objects.create(
277
type="text",
278
name="asset_tag",
279
label="Asset Tag"
280
)
281
```
282
283
**Job Creation:**
284
```python
285
from nautobot.extras.jobs import Job
286
287
class MyCustomJob(Job):
288
class Meta:
289
name = "My Custom Job"
290
description = "Custom automation job"
291
292
def run(self):
293
# Job logic here
294
pass
295
```