Skip to content

اینباندها ​

اینباند یک سرویس VPN است: شنوندهٔ OpenVPN، OpenConnect یا WireGuard روی یک نود. API آن را instances می‌نامد. اینباندی با nodeId: -1 هنوز تخصیص نیافته؛ 0 سرور پنل است. اینباند چندنودی برای هر نود یک استقرار دارد.

این مسیرها اینباندها را فهرست و تغییر می‌دهند، پیش‌فرض و دسترسی‌شان را می‌خوانند، مستقرشان می‌کنند، تنظیمات هر نود را بازنویسی می‌کنند، روشن و خاموششان می‌کنند و گزارششان را می‌خوانند. ترافیک با بایت و زمان با ثانیهٔ یونیکس است.

فهرست کوتاه ​

GET/api/instances/briefدسترسیinbounds.view

اینباندها را فقط با نام، وضعیت و آدرس برمی‌گرداند. ?deployments=1 استقرارهای هر نود را هم برای اینباند چندنودی می‌آورد.

bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" "$BASE/instances/brief?deployments=1"
json
[
  {
    "id": 12,
    "technicalName": "udp1194",
    "nodeId": 0,
    "node": "this server",
    "name": "udp1194",
    "proto": "udp",
    "port": 1194,
    "enabled": true,
    "authMode": "cert",
    "description": "",
    "network": "10.128.0.0/16",
    "staticStart": "10.128.255.0",
    "staticEnd": "10.128.255.255",
    "kind": "openvpn"
  }
]

فهرست اینباندها ​

GET/api/instancesدسترسیinbounds.view

به inbounds.view: all نیاز دارد. حساب با محدودهٔ own باید از GET instances/brief استفاده کند. اینباندها را با تنظیمات کامل، وضعیت پیوند، استخر آدرس، تعداد کاربر و استقرارها برمی‌گرداند. ?deployments=1 استقرار هر نود را می‌آورد.

bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" "$BASE/instances?deployments=1"
json
{
  "items": [
    {
      "id": 12,
      "kind": "openvpn",
      "nodeId": 0,
      "name": "udp1194",
      "enabled": true,
      "proto": "udp",
      "port": 1194,
      "network": "10.128.0.0/16",
      "active": true,
      "state": "active",
      "link": { "connected": true, "online": 3 },
      "clients": 42,
      "settings": { "authMode": "cert", "tlsMode": "tls-crypt" }
    }
  ],
  "system": "Ubuntu",
  "openvpn": "2.6.12",
  "publicHost": "panel.example.com"
}

ساخت اینباند ​

POST/api/instancesدسترسیinbounds.manage

پاسخ 201 با اینباند تازه است، و اگر بخشی از تغییر اعمال نشود warning دارد. تخصیص نود معمولاً درخواست جداست؛ nodeIds بلافاصله پس از ساخت مستقر می‌کند.

فیلدنوعلازممعنی
displayNamestringخیرنامی که به‌جای name نشان داده می‌شود.
kindstringخیرopenvpn، ocserv یا wireguard. خالی یعنی openvpn. بعد از ساخت ثابت است.
nodeIdintegerخیرهنگام ساخت نادیده گرفته می‌شود. اینباند تازه تخصیص‌نیافته (-1) است؛ برای استقرار از nodeIds استفاده کنید.
namestringبلهنام اینباند و نام سرویس. یکتا.
enabledbooleanخیرروشن باشد.
protostringبلهudp، tcp، udp6 یا tcp6.
portintegerبلهپورت شنود.
networkstringبلهشبکهٔ تونل به شکل CIDR.
settingsobjectخیرتنظیمات پروتکل. پایین را ببینید.
accessGroupsinteger[]خیرگروه‌هایی که می‌توانند از اینباند استفاده کنند. نبودنش همهٔ گروه‌ها را می‌دهد.
ownListClientsbooleanخیرکاربر بتواند مستقیم این اینباند را انتخاب کند. نبودنش یعنی بله.
nodeIdsinteger[]خیرنودهایی که بلافاصله پس از ساخت مستقر می‌شوند.
portsobjectخیرپورت هر نود استقرار، با کلید شناسهٔ نود.
bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" \
  -H "Content-Type: application/json" -X POST "$BASE/instances" \
  -d '{
    "kind": "openvpn",
    "name": "udp1194",
    "enabled": true,
    "proto": "udp",
    "port": 1194,
    "network": "10.128.0.0/16",
    "settings": {
      "authMode": "cert",
      "tlsMode": "tls-crypt",
      "dns": ["1.1.1.1"],
      "redirectGateway": true,
      "maxClients": 0
    },
    "accessGroups": [3]
  }'
json
{
  "instance": {
    "id": 12,
    "kind": "openvpn",
    "nodeId": -1,
    "name": "udp1194",
    "enabled": true,
    "proto": "udp",
    "port": 1194,
    "network": "10.128.0.0/16",
    "active": false,
    "state": "inactive",
    "clients": 0
  }
}

400 فیلد اشتباه، پورت استفاده‌شده یا شبکهٔ تونل هم‌پوشان را می‌گوید. 402 یعنی لایسنس اینباند دیگری را اجازه نمی‌دهد.

شیء تنظیمات ​

همهٔ فیلدها اختیاری‌اند؛ پنل مقدار ارسال‌نشده را با پیش‌فرض پر می‌کند. همان شیئی را که از GET instances/defaults یا GET instances/{id} خوانده‌اید پس از ویرایش بفرستید.

فیلدنوعمعنی
authModestringcert، cert+pass یا pass: نحوهٔ اثبات هویت کاربر.
tlsModestringtls-crypt، tls-auth یا none: حفاظت کانال کنترل.
dataCiphersstring[]رمزهای AEAD مذاکره‌شده.
fallbackCipherstringرمز کلاینت‌های پیش از ۲.۴؛ خالی یعنی هیچ.
authDigeststringخلاصهٔ HMAC.
tlsMinVersionstring1.2 یا 1.3.
dnsstring[]resolverهایی که به کاربران داده می‌شود.
searchDomainstringDOMAIN که به کاربران داده می‌شود.
redirectGatewaybooleanهمهٔ بسته‌ها از تونل بروند.
blockOutsideDnsbooleanDNS بیرون تونل بسته شود (رفع نشتی ویندوز).
pushRoutesstring[]CIDRهایی که از تونل می‌روند.
ipv6booleanآدرس تونل از network6 بده.
network6stringشبکهٔ تونل IPv6 به شکل CIDR.
clientToClientbooleanکاربران به هم برسند.
maxClientsintegerسقف کاربر هم‌زمان؛ 0 یعنی بی‌سقف.
keepaliveIntervalintegerفاصلهٔ keepalive به ثانیه.
keepaliveTimeoutintegerمهلت keepalive به ثانیه.
tunMtuintegerMTU تونل؛ 0 یعنی پیش‌فرض.
mssFixintegerمقدار MSS clamping؛ 0 یعنی خاموش.
fragmentintegerاندازهٔ قطعهٔ UDP؛ 0 یعنی خاموش.
sndRcvBufintegerاندازهٔ بافر سوکت؛ 0 یعنی پیش‌فرض سیستم.
compressionstringoff، lz4-v2 یا lzo.
renegSecintegerفاصلهٔ تمدید کلید به ثانیه.
portSharestringپورت میزبان برای اشتراک با سرویس دیگر؛ فقط TCP.
exitNotifybooleanهنگام توقف سرور به کاربران بگو.
multihomebooleanبه UDP از همان آدرسی پاسخ بده که بسته رسیده.
remotesobject[]آدرس کاربران: label، host، port. خالی یعنی آدرس‌های نود.
remotestringاولین remotes، برای نسخه‌های قدیمی‌تر.
verbintegerسطح گزارش، ۰ تا ۱۱.
natbooleanقاعدهٔ NAT برای شبکهٔ تونل نگه داشته شود.
serverCustomstringخطوط اضافهٔ تنظیمات سرور، بررسی‌شده با فهرست ممنوع.
clientCustomstringخطوط اضافهٔ تنظیمات کاربر، بررسی‌شده با فهرست ممنوع.
descriptionstringمتنی که با پروفایل‌های اینباند نشان داده می‌شود.
ocobjectتنظیمات OpenConnect.
wgobjectتنظیمات WireGuard.

تنظیمات OpenConnect (oc) ​

فیلدنوعمعنی
dtlsbooleanروی همان پورت UDP هم گوش بده.
camouflagebooleanبه کاوش مرورگر با صفحهٔ فریبنده پاسخ بده؛ ocserv 1.2.0 یا جدیدتر لازم است.
camouflageSecretstringراز داخل آدرس اتصال: https://host:port/?SECRET.
camouflageRealmstringقلمرویی که به مرورگر کاوشگر نشان داده می‌شود.
certSourcestringpki، panel یا acme: منبع گواهی سرور.
acmeHoststringنام DNS برای ACME؛ خالی یعنی آدرس عمومی نود.
idleTimeoutintegerمهلت بی‌فعالیتی کلاینت دسکتاپ، به ثانیه.
mobileIdleTimeoutintegerمهلت بی‌فعالیتی کلاینت موبایل، به ثانیه.
cookieTimeoutintegerمدت قابل‌ادامه بودن کوکی نشست، به ثانیه.
dpdintegerفاصلهٔ تشخیص همتای مرده، به ثانیه.
mobileDpdintegerهمان مقدار برای کلاینت موبایل، به ثانیه.
ciscoCompatbooleanکلاینت‌های قدیمی Cisco را بپذیر.
tlsPrioritiesstringرشتهٔ اولویت GnuTLS.
proxyProtocolbooleanهدرهای PROXY protocol از رله را بپذیر.
serverCustomstringخطوط اضافهٔ ocserv.conf، بررسی‌شده با فهرست ممنوع.

تنظیمات WireGuard (wg) ​

فیلدنوعمعنی
filenameTemplatestringنام فایل دانلودی کاربر: متن ثابت یا الگو با {username}، {device} و {inbound}. خالی یعنی نام‌گذاری خودکار. برای WireGuard و AmneziaWG.
privateKeystringکلید خصوصی سرور. API هرگز برنمی‌گرداند.
publicKeystringکلید عمومی سرور.
obfuscationstringحالت پوشش؛ خالی یعنی WireGuard ساده.
amneziaobjectپارامترهای AmneziaWG: jc، jmin، jmax، s1، s2، h1-h4، i1-i5، j1-j3، itime.
mtuintegerMTU تونل.
keepaliveintegerkeepalive دائمی به ثانیه؛ 0 یعنی خاموش.
allowedIPsstring[]CIDRهایی که از تونل می‌روند.

پیش‌بررسی اینباند ​

POST/api/instances/preflightدسترسیinbounds.manage

طرح را پیش از ساخت بررسی می‌کند. بدنه همان بدنهٔ ساخت به‌همراه nodeIds و ports هر نود است؛ nodeId نادیده گرفته می‌شود. پاسخ برای هر نود یک یافته دارد، با error خالی وقتی نود آماده است.

bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" \
  -H "Content-Type: application/json" -X POST "$BASE/instances/preflight" \
  -d '{"kind":"openvpn","name":"udp1194","proto":"udp","port":1194,"network":"10.128.0.0/16","nodeIds":[0,4]}'
json
{
  "items": [
    { "nodeId": 0, "error": "" },
    { "nodeId": 4, "error": "port udp/1194 is already used by udp1194" }
  ]
}

400 یعنی خود طرح معتبر نیست.

خواندن پیش‌فرض‌ها ​

GET/api/instances/defaultsدسترسیinbounds.manage

تنظیمات پیش‌فرض اینباند تازه را برمی‌گرداند. برای OpenConnect وضعیت نصب نود را هم می‌دهد.

پارامترمحلنوعمعنی
kindquerystringopenvpn، ocserv یا wireguard. پیش‌فرض openvpn.
nodeIdqueryintegerنودی که پیش‌فرض‌ها برایش است. -1 (پیش‌فرض) یعنی اینباند تخصیص‌نیافته.
bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" \
  "$BASE/instances/defaults?kind=openvpn&nodeId=0"
json
{
  "authMode": "cert",
  "tlsMode": "tls-crypt",
  "dataCiphers": ["AES-256-GCM", "CHACHA20-POLY1305"],
  "fallbackCipher": "",
  "authDigest": "SHA256",
  "tlsMinVersion": "1.2",
  "dns": ["1.1.1.1"],
  "redirectGateway": false,
  "blockOutsideDns": false,
  "pushRoutes": [],
  "ipv6": false,
  "network6": "",
  "clientToClient": false,
  "maxClients": 0,
  "keepaliveInterval": 10,
  "keepaliveTimeout": 60,
  "tunMtu": 0,
  "mssFix": 0,
  "fragment": 0,
  "sndRcvBuf": 0,
  "compression": "off",
  "renegSec": 0,
  "portShare": "",
  "exitNotify": false,
  "multihome": false,
  "remotes": [],
  "remote": "",
  "verb": 3,
  "nat": true,
  "serverCustom": "",
  "clientCustom": "",
  "description": ""
}

برای kind=ocserv پاسخ شیئی با settings و همچنین supported، installed، version، installing، installError، camouflageMin، camouflageOk، certSource، panelCert و acme است.

خواندن دسترسی اینباند ​

GET/api/instances/accessدسترسیinbounds.manage

گروه‌هایی که می‌توانند از هر اینباند استفاده کنند و تعداد کاربرانی که فهرست اینباند خودشان را دارند، نه گروه، را برمی‌گرداند.

bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" "$BASE/instances/access"
json
{
  "groups": [
    { "id": 3, "name": "Iran", "instances": [12, 21], "clients": 42 }
  ],
  "ownListClients": 7
}

نصب OpenConnect روی این سرور ​

POST/api/ocserv/installدسترسیinbounds.manage

نصب ocserv روی میزبان پنل را شروع می‌کند. پاسخ 202 است؛ نتیجهٔ همین سرور را از GET instances/defaults?kind=ocserv&nodeId=0 بخوانید.

bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" -X POST "$BASE/ocserv/install"

400 یعنی نصب روی این میزبان ممکن نیست.

خواندن یک اینباند ​

GET/api/instances/{id}دسترسیinbounds.view

اینباند، فایل تنظیمات رندرشده، محل فایل، استقرارها و بازنویسی‌ها را برمی‌گرداند. حساب باید inbounds.view برای همهٔ اینباندها داشته باشد.

bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" "$BASE/instances/12"
json
{
  "instance": {
    "id": 12,
    "kind": "openvpn",
    "nodeId": 0,
    "name": "udp1194",
    "enabled": true,
    "proto": "udp",
    "port": 1194,
    "network": "10.128.0.0/16",
    "active": true,
    "state": "active",
    "clients": 42,
    "settings": { "authMode": "cert", "tlsMode": "tls-crypt" }
  },
  "config": "port 1194\nproto udp\n...",
  "path": "/etc/ovira/instances/udp1194/server.conf",
  "shared": { "name": "udp1194", "port": 1194 },
  "overrides": {},
  "deployments": []
}

تغییر اینباند ​

PUT/api/instances/{id}دسترسیinbounds.manage

همان فیلدهای ساخت را می‌فرستد، بدون accessGroups، nodeIds و ports. پاسخ اینباند تغییرکرده با warning است وقتی بخشی از تغییر اعمال نشود.

bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" \
  -H "Content-Type: application/json" -X PUT "$BASE/instances/12" \
  -d '{"name":"udp1194","enabled":true,"proto":"udp","port":1194,"network":"10.128.0.0/16","settings":{"authMode":"cert+pass","tlsMode":"tls-crypt"}}'
json
{
  "instance": {
    "id": 12,
    "name": "udp1194",
    "enabled": true,
    "port": 1194,
    "settings": { "authMode": "cert+pass", "tlsMode": "tls-crypt" }
  }
}

400 فیلد اشتباه را می‌گوید. تغییر پورت یا شبکه اینباند را دوباره راه می‌اندازد و کاربرانش را قطع می‌کند.

حذف اینباند ​

DELETE/api/instances/{id}دسترسیinbounds.manage

اینباند و سرویسش را حذف می‌کند. کاربرانی که از آن استفاده می‌کردند آن پروفایل را از دست می‌دهند.

bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" -X DELETE "$BASE/instances/12"
json
{ "ok": true }

فهرست استقرارها ​

GET/api/instances/{id}/deploymentsدسترسیinbounds.view

برای هر نودی که اینباند رویش مستقر است یک ورودی با کار استقرار برمی‌گرداند. حساب باید inbounds.view برای همهٔ اینباندها داشته باشد.

bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" "$BASE/instances/12/deployments"
json
{
  "items": [
    {
      "nodeId": 4,
      "node": "de-fra-1",
      "instance": { "id": 27, "parentId": 12, "nodeId": 4, "name": "udp1194" },
      "job": {
        "serviceId": 12,
        "nodeId": 4,
        "instanceId": 27,
        "status": "done",
        "stage": "running",
        "logs": [],
        "updatedAt": 1795919000
      }
    }
  ]
}

استقرار اینباند ​

POST/api/instances/{id}/deploymentsدسترسیinbounds.manage

استقرار روی یک یا چند نود را در صف می‌گذارد.

فیلدنوعلازممعنی
nodeIdsinteger[]بله۱ تا ۱۰۰ نود برای استقرار.
portsobjectخیرپورت هر نود، با کلید شناسهٔ نود.

?check=1 را اضافه کنید تا نودها بررسی شوند، نه مستقر: پاسخ 200 با یک یافته برای هر نود است و چیزی تغییر نمی‌کند. بدون آن پاسخ 202 است و استقرارها در صف می‌روند.

bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$BASE/instances/12/deployments?check=1" \
  -d '{"nodeIds":[4],"ports":{"4":1194}}'
json
{
  "items": [
    { "nodeId": 4, "error": "" }
  ]
}

400 یعنی نودی انتخاب نشده، تعداد نودها زیاد است یا بدنه معتبر نیست.

حذف استقرار ​

DELETE/api/instances/{id}/deployments/{node}دسترسیinbounds.manage

اینباند را از یک نود حذف می‌کند. پارامترهای مسیر شناسهٔ اینباند و شناسهٔ نود هستند؛ 0 همین سرور.

bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" \
  -X DELETE "$BASE/instances/12/deployments/4"
json
{ "ok": true }

400 یعنی شناسه یا نود معتبر نیست، یا اینباند آنجا مستقر نیست.

تغییر بازنویسی‌های یک نود ​

PUT/api/instances/{id}/deployments/{node}/overridesدسترسیinbounds.manage

تعیین می‌کند یک نود برای اینباند چندنودی چه چیزی را بازنویسی کند. پاسخ 202 است و نود دوباره مستقر می‌شود.

فیلدنوعمعنی
portintegerپورت این نود به‌جای پورت مشترک.
networkstringشبکهٔ تونل این نود به‌جای شبکهٔ مشترک.
remotesobject[]آدرس کاربران این نود به‌جای آدرس‌های مشترک: label، host، port.
bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" \
  -H "Content-Type: application/json" \
  -X PUT "$BASE/instances/12/deployments/4/overrides" \
  -d '{"port":443,"remotes":[{"label":"Germany","host":"de.example.com","port":443}]}'
json
{ "ok": true }

400 یعنی اینباند روی آن نود مستقر نیست.

DELETE/api/instances/{id}/deployments/{node}/overridesدسترسیinbounds.manage

بازنویسی‌های آن نود را پاک و آن را دوباره مستقر می‌کند. پاسخ 202 است.

تخصیص اینباند به نود ​

POST/api/instances/{id}/nodeدسترسیinbounds.manage

اینباند را به یک نود منتقل می‌کند، از جمله از یک نود به نود دیگر. بدنه یک فیلد لازم دارد:

فیلدنوعلازممعنی
nodeIdintegerبلهنودی که تخصیص می‌یابد. 0 سرور پنل است.
bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" \
  -H "Content-Type: application/json" -X POST "$BASE/instances/12/node" \
  -d '{"nodeId":4}'

پاسخ اینباند و warning است وقتی بخشی اعمال نشود. 400 یعنی نودی انتخاب نشده یا معتبر نیست.

DELETE/api/instances/{id}/nodeدسترسیinbounds.manage

اینباند را از نودش جدا و تخصیص‌نیافته می‌کند. پروفایل‌هایش تا تخصیص دوباره از کار می‌افتند.

bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" -X DELETE "$BASE/instances/12/node"

400 یعنی اینباند جدا نمی‌شود.

شروع، توقف یا راه‌اندازی دوباره ​

POST/api/instances/{id}/controlدسترسیinbounds.manage
فیلدنوعلازممعنی
actionstringبلهstart، stop یا restart.
bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" \
  -H "Content-Type: application/json" -X POST "$BASE/instances/12/control" \
  -d '{"action":"restart"}'

پاسخ اینباند پس از کار است. 400 یعنی کار معتبر نیست.

خواندن گزارش اینباند ​

به inbounds.view: all نیاز دارد.

GET/api/instances/{id}/logsدسترسیinbounds.view
پارامترمحلنوعمعنی
idpathintegerشناسهٔ اینباند.
linesqueryintegerچند خط، ۱۰ تا ۲۰۰۰. مقدار دیگر یعنی ۲۰۰.
bash
curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" \
  "$BASE/instances/12/logs?lines=100"
json
{
  "logs": "2026-11-02 12:00:01 TLS: Initial packet from 203.0.113.9:51820\n..."
}

404 یعنی چنین اینباندی نیست.

صفحه‌های مرتبط ​

نرم‌افزار انحصاری · مستندات آزاد برای اشتراک