همهٔ سیستم‌ها عملیاتی‌اند
ایران‌کلاد
ورود ثبت‌نام

مرجع API · نسخهٔ v1

API گروه‌های قانون فایروال

مجموعه‌قانون‌های مشترک که روی چند سرور اعمال می‌شوند. این گروه با شناسهٔ firewall در فایل OpenAPI آمده و ۹ endpoint دارد.

نمونه‌های curl توکن را از متغیر محیطی IRANCLAUD_TOKEN می‌خوانند؛ ساخت توکن و تنظیم این متغیر در راهنمای شروع سریع آمده است.

توکن، خطاها و محدودیت نرخ openapi.yaml
GET /api/v1/firewall/rulesets #

List your firewall rule-sets

دسترسی لازم: firewall:read محدودیت نرخ: خواندن
پاسخ‌ها (۴)
  • 200 All rule-sets (unpaginated) data[]: uuidnamedescriptioncreated_at
  • 401 unauthenticated / token_invalid — missing or invalid token
  • 403 scope_missing — token lacks firewall:read
  • 429 rate_limited — read limit reached; wait Retry-After seconds (details.retry_after_sec)
نمونهٔ curl
curl 
curl \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  "https://iranclaud.ir/api/v1/firewall/rulesets"

بازگشت به فهرست این بخش

POST /api/v1/firewall/rulesets #

Create a rule-set

دسترسی لازم: firewall:write محدودیت نرخ: تغییر
فیلدهای بدنه (JSON) (۲)
name string
الزامی Unique per account — min 1 chars; max 64 chars
description string | null
اختیاری
نمونهٔ بدنهٔ درخواست (JSON)
application/json 
{
    "name": "web-servers",
    "description": "HTTP/HTTPS + SSH from office"
}
پاسخ‌ها (۵)
  • 200 Rule-set created (empty, not attached to any VM) data: uuidnamedescriptioncreated_at
  • 401 unauthenticated / token_invalid — missing or invalid token
  • 403 scope_missing — token lacks firewall:write
  • 422 validation_failed — details.fields.name: required, max 64 chars, or duplicate name
  • 429 rate_limited — write limit reached; wait Retry-After seconds (details.retry_after_sec)
نمونهٔ curl
curl 
curl -X POST \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"web-servers","description":"HTTP/HTTPS + SSH from office"}' \
  "https://iranclaud.ir/api/v1/firewall/rulesets"

بازگشت به فهرست این بخش

GET /api/v1/firewall/rulesets/{uuid} #

Get a rule-set with its rules and attached VMs

دسترسی لازم: firewall:read محدودیت نرخ: خواندن
پارامترهای مسیر (۱)
uuid string
الزامی Rule-set UUID (36 chars)
پاسخ‌ها (۵)
  • 200 Rule-set detail data: rulesetrulesvms
  • 401 unauthenticated / token_invalid — missing or invalid token
  • 403 scope_missing — token lacks firewall:read
  • 404 not_found — unknown rule-set or not yours
  • 429 rate_limited — read limit reached; wait Retry-After seconds (details.retry_after_sec)
نمونهٔ curl
curl 
curl \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  "https://iranclaud.ir/api/v1/firewall/rulesets/YOUR_UUID"

بازگشت به فهرست این بخش

DELETE /api/v1/firewall/rulesets/{uuid} #

Delete a rule-set (its rules are removed from all attached VMs first)

دسترسی لازم: firewall:write محدودیت نرخ: تغییر
پارامترهای مسیر (۱)
uuid string
الزامی Rule-set UUID (36 chars)
پاسخ‌ها (۵)
  • 200 Deleted data: deleted
  • 401 unauthenticated / token_invalid — missing or invalid token
  • 403 scope_missing — token lacks firewall:write
  • 404 not_found — unknown rule-set or not yours
  • 429 rate_limited — write limit reached; wait Retry-After seconds (details.retry_after_sec)
نمونهٔ curl
curl 
curl -X DELETE \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  "https://iranclaud.ir/api/v1/firewall/rulesets/YOUR_UUID"

بازگشت به فهرست این بخش

POST /api/v1/firewall/rulesets/{uuid}/rules #

Add a rule (applied to every attached VM)

دسترسی لازم: firewall:write محدودیت نرخ: تغییر
پارامترهای مسیر (۱)
uuid string
الزامی Rule-set UUID (36 chars)
فیلدهای بدنه (JSON) (۵)
action string
الزامی Case-insensitive — one of: ACCEPT | DROP
protocol string
الزامی Case-insensitive — one of: tcp | udp | icmp
dport string
اختیاری Required for tcp/udp: single port "22" or range "8000:8999"; ignored for icmp — pattern ^[0-9]{1,5}(:[0-9]{1,5})?$
source string
اختیاری CIDR with prefix (IPv4 or IPv6), e.g. 203.0.113.0/24 — default: 0.0.0.0/0
comment string | null
اختیاری
نمونهٔ بدنهٔ درخواست (JSON)
application/json 
{
    "action": "ACCEPT",
    "protocol": "tcp",
    "dport": "22",
    "source": "203.0.113.0/24",
    "comment": "SSH from office"
}
پاسخ‌ها (۶)
  • 200 Rule added data: rule_id
  • 401 unauthenticated / token_invalid — missing or invalid token
  • 403 scope_missing — token lacks firewall:write
  • 404 not_found — unknown rule-set or not yours
  • 422 validation_failed — details.fields.{action|protocol|dport|source}
  • 429 rate_limited — write limit reached; wait Retry-After seconds (details.retry_after_sec)
نمونهٔ curl
curl 
curl -X POST \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"ACCEPT","protocol":"tcp","dport":"22","source":"203.0.113.0/24","comment":"SSH from office"}' \
  "https://iranclaud.ir/api/v1/firewall/rulesets/YOUR_UUID/rules"

بازگشت به فهرست این بخش

DELETE /api/v1/firewall/rulesets/{uuid}/rules/{rid} #

Delete a rule (removed from every attached VM)

دسترسی لازم: firewall:write محدودیت نرخ: تغییر
پارامترهای مسیر (۲)
uuid string
الزامی Rule-set UUID (36 chars)
rid integer
الزامی Rule ID (the "id" field of a rule, not its position)
پاسخ‌ها (۵)
  • 200 Deleted (also returned when the rule id does not exist in this rule-set) data: deleted
  • 401 unauthenticated / token_invalid — missing or invalid token
  • 403 scope_missing — token lacks firewall:write
  • 404 not_found — unknown rule-set or not yours
  • 429 rate_limited — write limit reached; wait Retry-After seconds (details.retry_after_sec)
نمونهٔ curl
curl 
curl -X DELETE \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  "https://iranclaud.ir/api/v1/firewall/rulesets/YOUR_UUID/rules/YOUR_RID"

بازگشت به فهرست این بخش

POST /api/v1/firewall/rulesets/{uuid}/vms/{vm_uuid} #

Attach a rule-set to a VM and apply it immediately

دسترسی لازم: firewall:write محدودیت نرخ: تغییر
پارامترهای مسیر (۲)
uuid string
الزامی Rule-set UUID (36 chars)
vm_uuid string
الزامی VM UUID (36 chars); must be one of your VMs
پاسخ‌ها (۶)
  • 200 Attached and applied data: attached
  • 401 unauthenticated / token_invalid — missing or invalid token
  • 403 scope_missing — token lacks firewall:write
  • 404 not_found — unknown rule-set or VM, or not yours
  • 429 rate_limited — write limit reached; wait Retry-After seconds (details.retry_after_sec)
  • 503 sync_failed — attached, but applying the rules to the VM failed; retry with POST …/sync
نمونهٔ curl
curl 
curl -X POST \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  "https://iranclaud.ir/api/v1/firewall/rulesets/YOUR_UUID/vms/YOUR_VM_UUID"

بازگشت به فهرست این بخش

DELETE /api/v1/firewall/rulesets/{uuid}/vms/{vm_uuid} #

Detach a rule-set from a VM (its rules are removed from the VM)

دسترسی لازم: firewall:write محدودیت نرخ: تغییر
پارامترهای مسیر (۲)
uuid string
الزامی Rule-set UUID (36 chars)
vm_uuid string
الزامی VM UUID (36 chars); must be one of your VMs
پاسخ‌ها (۵)
  • 200 Detached data: detached
  • 401 unauthenticated / token_invalid — missing or invalid token
  • 403 scope_missing — token lacks firewall:write
  • 404 not_found — unknown rule-set or VM, or not yours
  • 429 rate_limited — write limit reached; wait Retry-After seconds (details.retry_after_sec)
نمونهٔ curl
curl 
curl -X DELETE \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  "https://iranclaud.ir/api/v1/firewall/rulesets/YOUR_UUID/vms/YOUR_VM_UUID"

بازگشت به فهرست این بخش

POST /api/v1/firewall/rulesets/{uuid}/sync #

Re-apply a rule-set to all attached VMs

دسترسی لازم: firewall:write محدودیت نرخ: تغییر
پارامترهای مسیر (۱)
uuid string
الزامی Rule-set UUID (36 chars)
پاسخ‌ها (۵)
  • 200 Per-VM result map (keyed by internal VM id): {ok: bool, error?: string} data: result
  • 401 unauthenticated / token_invalid — missing or invalid token
  • 403 scope_missing — token lacks firewall:write
  • 404 not_found — unknown rule-set or not yours
  • 429 rate_limited — write limit reached; wait Retry-After seconds (details.retry_after_sec)
نمونهٔ curl
curl 
curl -X POST \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  "https://iranclaud.ir/api/v1/firewall/rulesets/YOUR_UUID/sync"

بازگشت به فهرست این بخش

همهٔ گروه‌های API