مقدمه
NetBox یک پلتفرم متنباز برای مدلسازی و مستندسازی زیرساخت شبکه است که نقش Source of Truth را برای IPAM، DCIM، Rack، Device، Cable، VLAN، Prefix، Virtualization و سایر منابع زیرساختی ایفا میکند. این راهنما نصب Production-ready نسخه 4.7.x روی Ubuntu 24.04 را از صفر تا API و Import کتابخانه تجهیزات پوشش میدهد.
در زمان تهیه این راهنما آخرین نسخه پایدار NetBox، نسخه 4.7.1 منتشرشده در 15 سپتامبر 2026 است. برای محیط Production بهتر است همیشه آخرین Patch همان شاخه پایدار را نصب کنید و قبل از Upgrade یادداشتهای Release را بررسی کنید.
فهرست مطالب
معماری NetBox
NetBox یک برنامه Django/Python است که در Production معمولاً پشت Gunicorn و Nginx اجرا میشود. PostgreSQL دیتابیس اصلی است و Redis برای Cache و صف Background Jobها استفاده میشود. سرویس netbox-rq پردازش Jobهای پسزمینه را انجام میدهد.
- Nginx: Reverse Proxy، TLS و ارائه Static Files
- Gunicorn: اجرای WSGI Application
- NetBox/Django: منطق اصلی برنامه
- PostgreSQL 15+: پایگاه داده اصلی
- Redis 6+: Cache و Queue
- netbox-rq: Worker پردازش Background Jobs
چه سروری برای NetBox نیاز داریم؟
مستندات رسمی NetBox حداقل CPU/RAM مشخصی تعیین نمیکنند و ظرفیت مناسب به تعداد کاربران، Deviceها، Pluginها و حجم Automation بستگی دارد. جدول زیر یک پیشنهاد عملی برای شروع است، نه الزام رسمی NetBox.
| Environment | vCPU | RAM | Disk | Use |
|---|---|---|---|---|
| Lab / Test | 2 | 4 GB | 30 GB SSD | آزمایش و آموزش |
| Small Production | 4 | 8 GB | 60 GB SSD | چند هزار Object و کاربران محدود |
| Medium Production | 8 | 16 GB | 100+ GB SSD | Automation، Plugin و API پرترافیک |
- برای Production از SSD استفاده کنید و PostgreSQL را روی Storage پایدار قرار دهید.
- در محیطهای بزرگ میتوانید PostgreSQL و Redis را روی سرورهای جداگانه اجرا کنید.
- پورتهای عمومی موردنیاز معمولاً 80/443 هستند؛ PostgreSQL و Redis را عمومی نکنید.
پیشنیازهای رسمی
- Ubuntu Server 24.04 LTS؛ مستندات نصب رسمی NetBox روی این نسخه تست شدهاند.
- Python 3.12، 3.13 یا 3.14
- PostgreSQL 15 یا بالاتر؛ MySQL پشتیبانی نمیشود.
- Redis 6.0 یا بالاتر
- کاربر دارای sudo، اینترنت، DNS/FQDN و ترجیحاً SSL معتبر
sudo apt update && sudo apt upgrade -y
sudo timedatectl set-timezone Asia/Tehran
hostnamectl
ip a
اگر سرور شما در منطقه زمانی دیگری قرار دارد، مقدار timezone را متناسب با محیط خود تغییر دهید.
نصب و راهاندازی PostgreSQL
sudo apt update
sudo apt install -y postgresql
psql -V
systemctl status postgresql --no-pager
NetBox 4.7 به PostgreSQL 15 یا بالاتر نیاز دارد. سپس Database و User اختصاصی بسازید. رمز مثال زیر را حتماً تغییر دهید.
sudo -u postgres psql
CREATE DATABASE netbox;
CREATE USER netbox WITH PASSWORD 'CHANGE_THIS_STRONG_PASSWORD';
ALTER DATABASE netbox OWNER TO netbox;
\connect netbox;
GRANT CREATE ON SCHEMA public TO netbox;
\q
اتصال دیتابیس را قبل از ادامه تست کنید:
psql --username netbox --password --host localhost netbox
# سپس در psql:
\conninfo
\q
نصب و راهاندازی Redis
sudo apt install -y redis-server
redis-server -v
redis-cli ping
systemctl status redis-server --no-pager
خروجی redis-cli ping باید PONG باشد. Redis را روی localhost یا شبکه Trusted نگه دارید؛ Workerهای NetBox Jobها را از Redis دریافت میکنند و دسترسی Write غیرمجاز به Redis یک ریسک امنیتی جدی است.
نصب NetBox روی Ubuntu 24.04
برای Production از روش Release Archive یا Git استفاده کنید. نصب NetBox از Python package در شاخه 4.7 هنوز Experimental است. در این راهنما روش Git استفاده میشود تا Upgradeها سادهتر باشند.
sudo apt install -y python3 python3-pip python3-venv python3-dev \
build-essential libxml2-dev libxslt1-dev libffi-dev libpq-dev \
libssl-dev zlib1g-dev git
python3 -V
Repository رسمی را Clone کرده و نسخه پایدار را Checkout کنید. در تاریخ این راهنما آخرین Patch، نسخه v4.7.1 است.
sudo mkdir -p /opt/netbox
cd /opt/netbox
sudo git clone https://github.com/netbox-community/netbox.git .
sudo git checkout v4.7.1
سپس Service Account مخصوص NetBox را بسازید و مالکیت مسیرهای قابل نوشتن را تنظیم کنید.
sudo adduser --system --group netbox
sudo chown --recursive netbox /opt/netbox/netbox/media/
sudo chown --recursive netbox /opt/netbox/netbox/reports/
sudo chown --recursive netbox /opt/netbox/netbox/scripts/
پیکربندی اصلی NetBox
cd /opt/netbox/netbox/netbox
sudo cp configuration_example.py configuration.py
sudo nano configuration.py
در NetBox 4.7 پنج پارامتر اصلی برای نصب جدید ضروری هستند: ALLOWED_HOSTS، API_TOKEN_PEPPERS، DATABASES، REDIS و SECRET_KEY.
cd /opt/netbox/netbox
python3 generate_secret_key.py
python3 generate_secret_key.py
دو مقدار مستقل بسازید: یکی برای SECRET_KEY و دیگری برای API_TOKEN_PEPPERS. مقادیر زیر Placeholder هستند.
ALLOWED_HOSTS = ['netbox.example.com', '10.10.10.20']
API_TOKEN_PEPPERS = {
1: 'PUT_A_RANDOM_50_PLUS_CHARACTER_VALUE_HERE',
}
DATABASES = {
'default': {
'NAME': 'netbox',
'USER': 'netbox',
'PASSWORD': 'CHANGE_THIS_STRONG_PASSWORD',
'HOST': 'localhost',
'PORT': '',
'CONN_MAX_AGE': 300,
}
}
REDIS = {
'tasks': {
'HOST': 'localhost',
'PORT': 6379,
'PASSWORD': '',
'DATABASE': 0,
'SSL': False,
},
'caching': {
'HOST': 'localhost',
'PORT': 6379,
'PASSWORD': '',
'DATABASE': 1,
'SSL': False,
}
}
SECRET_KEY = 'PUT_ANOTHER_RANDOM_50_PLUS_CHARACTER_VALUE_HERE'
حالا اسکریپت نصب/Upgrade را اجرا کنید؛ این اسکریپت Virtual Environment، Python dependencies، Migrationها، Documentation و Static Files را آماده میکند.
sudo /opt/netbox/upgrade.sh
در پایان Superuser بسازید:
source /opt/netbox/venv/bin/activate
cd /opt/netbox/netbox
python3 manage.py createsuperuser
راهاندازی Gunicorn و سرویسهای systemd
sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now netbox netbox-rq
سرویس netbox مربوط به Gunicorn و سرویس netbox-rq مربوط به Background Worker است. هر دو باید Active باشند.
systemctl status netbox --no-pager
systemctl status netbox-rq --no-pager
ss -lntp | grep 8001
راهاندازی Nginx و HTTPS
sudo apt install -y nginx
sudo cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox
sudo nano /etc/nginx/sites-available/netbox
در فایل Nginx مقدار netbox.example.com را با FQDN یا IP خود جایگزین کنید. مقدار باید با ALLOWED_HOSTS هماهنگ باشد. فایل نمونه NetBox بهطور پیشفرض Gunicorn را روی پورت 8001 Reverse Proxy میکند.
sudo rm -f /etc/nginx/sites-enabled/default
sudo ln -s /etc/nginx/sites-available/netbox /etc/nginx/sites-enabled/netbox
sudo nginx -t
sudo systemctl restart nginx
sudo systemctl enable nginx
برای Production از Certificate معتبر استفاده کنید. اگر DNS عمومی دارید میتوانید Let’s Encrypt/Certbot را بهکار ببرید؛ در شبکه داخلی میتوانید Certificate سازمانی نصب کنید.
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d netbox.example.com
sudo certbot renew --dry-run
تست نهایی و بالا آمدن NetBox
curl -I http://127.0.0.1
curl -kI https://netbox.example.com
systemctl is-active postgresql redis-server netbox netbox-rq nginx
برای عیبیابی سریع وضعیت و Logها را بررسی کنید:
journalctl -eu netbox --no-pager -n 100
journalctl -eu netbox-rq --no-pager -n 100
tail -n 100 /var/log/nginx/error.log
- HTTP 502 معمولاً یعنی Nginx به Gunicorn روی 8001 دسترسی ندارد یا سرویس netbox Down است.
- HTTP 400 Bad Request معمولاً ALLOWED_HOSTS اشتباه است.
- خطاهای DB را با psql و journalctl بررسی کنید.
راهاندازی و تست REST API
تمام REST APIهای NetBox زیر مسیر /api/ قرار دارند و مستندات تعاملی Swagger روی /api/schema/swagger-ui/ در دسترس است. برای Automation از API Token استفاده کنید. در NetBox 4.5 به بعد توکنهای v2 توصیه میشوند و v1 در 4.6 Deprecated شده است.
- از UI وارد Profile → API Tokens شوید.
- توکن Write-enabled را فقط برای Import/Automation نیازمند تغییر بسازید.
- در صورت امکان Allowed IPs را به IP سرور Automation محدود کنید.
- Token plaintext را همان لحظه امن ذخیره کنید؛ بعداً قابل بازیابی نیست.
export NETBOX_URL='https://netbox.example.com'
export NETBOX_TOKEN='nbt_xxxxx.xxxxxxxxxxxxxxxxx'
curl -s \
-H "Authorization: Bearer $NETBOX_TOKEN" \
-H "Accept: application/json; indent=2" \
"$NETBOX_URL/api/dcim/sites/"
برای ساخت یک Site آزمایشی از API:
curl -s -X POST \
-H "Authorization: Bearer $NETBOX_TOKEN" \
-H "Content-Type: application/json" \
"$NETBOX_URL/api/dcim/sites/" \
--data '{"name":"HQ","slug":"hq","status":"active"}'
Import کردن Device Type Library با API
NetBox Community Device Type Library مجموعه بزرگی از تعریفهای YAML برای Manufacturer، Device Type، Module Type، Interface Template، Power Port و سایر Componentهاست. برای Import خودکار میتوان از پروژه Community به نام Device-Type-Library-Import استفاده کرد که به API NetBox متصل میشود، Duplicateها را بررسی میکند و امکان Import انتخابی Vendorها را دارد.
بهتر است Import Tool را داخل Virtual Environment جداگانه اجرا کنید و آن را داخل venv اصلی NetBox نصب نکنید.
sudo mkdir -p /opt/netbox-tools
sudo chown $USER:$USER /opt/netbox-tools
cd /opt/netbox-tools
git clone https://github.com/netbox-community/Device-Type-Library-Import.git
cd Device-Type-Library-Import
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
فایل Environment را بسازید و URL و Token دارای Write Permission را وارد کنید:
cp .env.example .env
nano .env
# نمونه:
NETBOX_URL=https://netbox.example.com/
NETBOX_TOKEN=nbt_xxxxx.xxxxxxxxxxxxxxxxx
اول فقط Vendorهای موردنیاز را Import کنید. این کار هم زمان اجرا و هم حجم داده را کاهش میدهد.
./nb-dt-import.py --vendors cisco,hpe,mikrotik,ubiquiti
برای Import همه Vendorها میتوانید ابزار را بدون --vendors اجرا کنید، ولی در Production بهتر است ابتدا روی Test/Staging بررسی شود. Repository کتابخانه هنگام اجرا Clone یا Pull میشود.
./nb-dt-import.py
برای تست API قبل از Import و مشاهده Manufacturerها:
curl -s \
-H "Authorization: Bearer $NETBOX_TOKEN" \
"$NETBOX_URL/api/dcim/manufacturers/?limit=5"
- خطای 401/403: Token، Permission و Allowed IPs را بررسی کنید.
- خطای SSL: Certificate chain را اصلاح کنید؛ غیرفعالکردن Verify فقط برای تست توصیه میشود.
- قبل از Import انبوه از دیتابیس Backup بگیرید.
- Device Typeهای Community را قبل از استفاده عملی با مدل واقعی سختافزار Verify کنید.
Backup، Upgrade و نگهداری
مهمترین بخش Backup، دیتابیس PostgreSQL است. علاوه بر آن configuration.py، media و در صورت استفاده scripts/reports سفارشی را نگه دارید.
sudo -u postgres pg_dump -Fc netbox > /var/backups/netbox-$(date +%F).dump
sudo cp /opt/netbox/netbox/netbox/configuration.py /var/backups/configuration.py
sudo tar -czf /var/backups/netbox-media-$(date +%F).tar.gz /opt/netbox/netbox/media
برای Upgrade در نصب Git، ابتدا Release Notes و سازگاری Pluginها را بررسی کنید، Backup بگیرید و سپس Tag جدید را Checkout کنید.
cd /opt/netbox
sudo git fetch --tags
sudo git checkout v4.7.1
sudo /opt/netbox/upgrade.sh
sudo systemctl restart netbox netbox-rq
systemctl status netbox netbox-rq --no-pager
چکلیست امنیت Production
- NetBox، PostgreSQL و Redis را با آخرین Patchهای امنیتی نگه دارید.
- PostgreSQL 5432 و Redis 6379 را Public نکنید.
- از HTTPS معتبر استفاده کنید و HTTP را Redirect کنید.
- برای API از Token v2 با حداقل Permission و Allowed IPs استفاده کنید.
- SECRET_KEY، API_TOKEN_PEPPERS و Database Password را در Repository ذخیره نکنید.
- Backupها را Encrypt و Restore آنها را دورهای تست کنید.
- برای کاربران عادی Role/Permission محدود تعریف کنید و Superuser را برای کار روزمره استفاده نکنید.
عیبیابی رایج
| خطا | بررسی | راهحل معمول |
|---|---|---|
| 502 Bad Gateway | systemctl status netbox | Gunicorn/port 8001 و Nginx proxy_pass را بررسی کنید. |
| 400 Bad Request | ALLOWED_HOSTS | FQDN/IP صحیح را در configuration.py قرار دهید. |
| DB connection failed | psql -h localhost -U netbox netbox | User/Password/HOST و PostgreSQL service را بررسی کنید. |
| Redis error | redis-cli ping | Redis service و تنظیم Database IDهای 0 و 1 را بررسی کنید. |
| API 403 | Token permission | Write enabled، User permissions و Allowed IPs را بررسی کنید. |
| Static/CSS مشکل دارد | sudo /opt/netbox/upgrade.sh | collectstatic و Nginx static path را بررسی کنید. |
sudo nginx -t
sudo systemctl restart netbox netbox-rq nginx
journalctl -eu netbox -n 150 --no-pager
journalctl -eu netbox-rq -n 150 --no-pager
tail -f /var/log/nginx/error.log
نتیجهگیری
با این معماری، NetBox روی Ubuntu 24.04 با PostgreSQL، Redis، Gunicorn و Nginx بهصورت Production-ready اجرا میشود. پس از بالا آمدن سرویس، REST API و Device Type Library پایه مناسبی برای Automation و مستندسازی استاندارد زیرساخت شبکه ایجاد میکنند.
پرسشهای متداول
NetBox دقیقاً چه کاری انجام میدهد؟
NetBox یک Source of Truth برای مدلسازی IPAM، DCIM، Rack، Device، Cable، VLAN، Prefix، Circuit، Virtualization و سایر منابع زیرساختی است؛ ابزار Monitoring مستقیم نیست.
آیا NetBox جای Zabbix یا PRTG را میگیرد؟
خیر. NetBox وضعیت مطلوب و مستندات زیرساخت را نگه میدارد؛ Zabbix/PRTG وضعیت عملیاتی و Metrics را مانیتور میکنند. این ابزارها میتوانند با API به NetBox متصل شوند.
برای NetBox 4.7 چه نسخههایی لازم است؟
Python 3.12 تا 3.14، PostgreSQL 15 یا بالاتر و Redis 6.0 یا بالاتر.
آیا MySQL یا SQL Server پشتیبانی میشود؟
خیر. NetBox به PostgreSQL نیاز دارد.
آیا میتوان PostgreSQL و Redis را روی سرور جدا نصب کرد؟
بله. در محیطهای بزرگ یا HA این معماری رایج است؛ HOST و Credentialها را در configuration.py تغییر دهید و Firewall را فقط بین Hostهای موردنیاز باز کنید.
آیا پورت 8000 یا 8001 باید از اینترنت باز باشد؟
خیر. در Production فقط Nginx روی 80/443 در دسترس باشد. Gunicorn روی 8001 باید داخلی باشد و runserver روی 8000 فقط برای تست است.
خطای 502 Bad Gateway یعنی چه؟
معمولاً Nginx نمیتواند به Gunicorn متصل شود. وضعیت netbox.service، پورت 8001 و proxy_pass را بررسی کنید.
خطای DisallowedHost یا 400 را چطور حل کنم؟
FQDN یا IP مورد استفاده را به ALLOWED_HOSTS اضافه کرده و سرویس NetBox را Restart کنید.
چطور API Token بسازم؟
از Profile → API Tokens یک Token v2 بسازید. مقدار plaintext را همان لحظه ذخیره کنید؛ بعداً قابل بازیابی نیست.
برای Import کتابخانه تجهیزات چه Permission لازم است؟
Token باید Write-enabled باشد و User آن روی Manufacturer، Device Type، Module Type و Componentهای مرتبط Permission ایجاد/تغییر داشته باشد.
آیا Device Type Library رسمی خود NetBox است؟
این Library در NetBox Community نگهداری میشود و تعریفها Community-sourced هستند. قبل از استفاده Production مشخصات را با سختافزار واقعی Verify کنید.
بهتر است همه Vendorها را Import کنم؟
معمولاً نه. Import انتخابی Vendorهای موردنیاز Database را تمیزتر نگه میدارد و زمان Import را کاهش میدهد.
چطور از NetBox Backup بگیرم؟
حداقل PostgreSQL dump، configuration.py و media را Backup کنید. اگر Custom Script/Report دارید آنها را هم نگه دارید و Restore را دورهای تست کنید.
Upgrade NetBox چگونه انجام میشود؟
Release Notes و Plugin compatibility را بررسی کنید، Backup بگیرید، Tag جدید را Checkout کنید، upgrade.sh را اجرا کرده و netbox/netbox-rq را Restart کنید.
آیا میتوان NetBox را بدون Nginx اجرا کرد؟
برای تست میتوان از runserver استفاده کرد، اما برای Production توصیه رسمی استفاده از یک HTTP Server مثل Nginx یا Apache در جلوی WSGI است.
Swagger API کجاست؟
روی هر Instance مسیر /api/schema/swagger-ui/ مستندات تعاملی OpenAPI را نمایش میدهد.
چطور وضعیت همه سرویسها را سریع بررسی کنم؟
از systemctl is-active postgresql redis-server netbox netbox-rq nginx استفاده کنید و برای خطا journalctl -eu netbox را ببینید.