نام (NAME)

slurmrestd - رابط کاربری Slurm از طریق REST API.

خلاصه دستور (SYNOPSIS)

slurmrestd [OPTIONS...] <[host]:port|unix:/path/to/socket>...

توضیحات (DESCRIPTION)

slurmrestd رابط REST API برای Slurm است. این دیمن می‌تواند در دو حالت استفاده شود:

حالت Inetd (Inetd Mode): slurmrestd روی ورودی/خروجی استاندارد (STDIO) می‌خواند و می‌نویسد. اگر STDIN یک توصیف‌کننده فایل (file descriptor) سوکت باشد، slurmrestd آن را تشخیص داده و از قابلیت‌های مربوطه استفاده می‌کند. این حالت برای کار با ورودی لوله‌کشی‌شده (piped input)، inetd، xinetd یا فعال‌سازی سوکت توسط systemd طراحی شده است.

حالت شنود (Listen Mode): slurmrestd یک سوکت شنود روی هر جفت host:port یا سوکت یونیکسِ درخواستی باز می‌کند.

گزینه‌ها (OPTIONS)

[https://][host]:port

نام میزبان و درگاه (port) برای شنود. host می‌تواند یک آدرس IPv4/IPv6 یا یک نام میزبان قابل‌حل (resolvable) باشد. نام‌های میزبان تنها در زمان راه‌اندازی واکشی می‌شوند و در طول چرخه حیات فرآیند تغییر نمی‌کنند. مشخص کردن host اختیاری است؛ اگر ارائه نشود، slurmrestd روی تمام رابط‌های شبکه شنود خواهد کرد. https:// اختیاری است؛ اگر مشخص نشود، slurmrestd در صورت امکان به‌طور خودکار از افزونه TLS برای رمزگذاری ترافیک استفاده می‌کند. اگر https:// تعیین شده باشد، slurmrestd الزامی می‌کند که افزونه TLS پیکربندی‌شده ترافیک را رمزگذاری کند.

unix:///path/to/socket

شنود روی سوکت محلی یونیکس. باید مجوز لازم برای ایجاد سوکت در سیستم فایل وجود داشته باشد.

-a <plugin>[,plugin]...

فهرست جداشده با کاما از افزونه‌های احراز هویت برای بارگذاری. به‌طور پیش‌فرض، تمام افزونه‌های احراز هویت در دسترس بارگذاری خواهند شد.

-d <plugin>[,plugin]...

فهرست جداشده با کاما از افزونه‌های data_parser که قالب خروجی را تعیین می‌کنند. می‌تواند شامل فلگ‌های اختیاری باشد که با نماد «+» مشخص می‌شوند. به‌طور پیش‌فرض، تمام افزونه‌های data_parser در دسترس بدون هیچ فلگ اختیاری بارگذاری خواهند شد. همچنین برای افزونه‌های OpenAPI که محتوای در دسترس را کنترل می‌کنند، -s را ببینید. پیش‌فرض: تمام افزونه‌های data_parser توکار پشتیبانی‌شده.

-f <file>

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

--generate-openapi-spec

تخلیه (dump) مشخصات OpenAPI با فرمت JSON در stdout و خروج فوری. حداقل افزونه‌های مورد نیاز را بارگذاری می‌کند. تمام فیلدهای «content» فقط با فرمت JSON خواهند بود حتی اگر افزونه serializer/yaml موجود و قابل بارگذاری باشد. بارگذاری slurm.conf(5) می‌تواند با ارسال آرگومان‌های اضافی -f /dev/null یا تنظیم SLURM_CONF=/dev/null در محیط غیرفعال شود.

-g <group id>

تغییر شناسه گروه (group id) (و رها کردن گروه‌های تکمیلی) پیش از پردازش درخواست کلاینت. این باید یک گروه یکتا و بدون دسترسی نوشتن یا مجوزهای ویژه باشد. این را روی گروه متعلق به SlurmUser یا ریشه (root) تنظیم نکنید، در غیر این صورت دیمن با تنظیمات پیش‌فرض شروع به کار نخواهد کرد.

-h, --help

راهنما؛ چاپ خلاصه‌ای کوتاه از گزینه‌های دستور.

--max-connections <count>

تنظیم حداکثر تعداد اتصال‌هایی که در هر لحظه پردازش می‌شوند. این مستقل از تعداد اتصال‌هایی است که می‌توانند در هر لحظه به slurmrestd متصل شوند. هنگامی که کوکی‌های SYN فعال باشند، هسته به هر تعداد اتصال اجازه می‌دهد تا در وضعیت تعلیق برای پردازش قرار گیرند.

-s <plugin>[,plugin]...

فهرست جداشده با کاما از افزونه‌های OpenAPI برای بارگذاری، که محتوای در دسترس را مشخص می‌کنند. به‌طور پیش‌فرض، اگر AccountingStorageType=accounting_storage/slurmdbd در slurm.conf(5) پیکربندی شده باشد، افزونه‌های OpenAPI بارگذاری‌شده slurmctld,slurmdbd و برای هر پیکربندی دیگری slurmctld خواهند بود. همچنین برای افزونه‌های data_parser که قالب خروجی را کنترل می‌کنند، -d را ببینید.

-t <THREAD COUNT>

مشخص کردن تعداد ریسه‌ها (threads) برای پردازش اتصالات کلاینت. در حالت inetd نادیده گرفته می‌شود.

-u <user id>

تغییر شناسه کاربری (user id) پیش از پردازش درخواست کلاینت. این باید یک کاربر یکتا و بدون دسترسی نوشتن یا مجوزهای ویژه باشد. این کاربر را روی SlurmUser یا ریشه (root) تنظیم نکنید، در غیر این صورت دیمن با تنظیمات پیش‌فرض شروع به کار نخواهد کرد.

-v

عملیات پرگو (verbose). می‌توان چندین v مشخص کرد که هر 'v' فراتر از اولی، میزان پرگویی گزارش‌ها را افزایش می‌دهد، تا حداکثر ۶ بار (یعنی -vvvvvv). سطوح بالاتر پرگویی تأثیر چشمگیری بر کارایی خواهند داشت. برای توضیحات مقاصد ثبت گزارش، SLURMRESTD_DEBUG را ببینید.

-V

چاپ اطلاعات نسخه و خروج.

تی‌ال‌اس (TLS)

slurmrestd از رمزگذاری TLS از طریق رابط افزونه TLS پشتیبانی می‌کند. برای توضیحات دقیق درباره پشتیبانی از TLS در Slurm، به https://slurm.schedmd.com/tls.html مراجعه کنید.

slurmrestd از رمزگذاری TLS برای اتصالات ورودی HTTPS، صرف‌نظر از چگونگی پیکربندی TLSType در slurm.conf(5)، پشتیبانی می‌کند. پیکربندی TLSParameters در slurm.conf(5) همیشه اعمال می‌شود. این امر اجازه می‌دهد تا لایه RPC اسلورم بدون رمزگذاری TLS باقی بماند، در حالی که slurmrestd امکان سرویس‌دهی به درخواست‌های HTTPS را از طریق TLS دارد.

slurmrestd شامل تشخیص خودکار اتصالات ورودی TLS است. اگر افزونه TLS کاملاً پیکربندی شده و در زمان راه‌اندازی با موفقیت بارگذاری شود، تمام اتصالات ورودی جدید برای دست‌تکانی‌های (handshakes) پروتکل SSLv3 (مطابق با RFC#6101) و TLSv1.x (مطابق با RFC#8446) اثرانگشت‌نگاری (fingerprint) می‌شوند. پس از تطابق اثرانگشت، هر یک از اتصالات ورودی در طول مدت اتصال، از طریق افزونه TLS پیکربندی‌شده رمزگذاری خواهند شد. پشتیبانی از TLS صرف‌نظر از اینکه اتصال از نوع socket(2) [unix(2)] یا pipe(2) (در حالت INETD) باشد، مدیریت می‌شود. اتصالات شنودی که با https:// ایجاد شده‌اند، ملزم به رمزگذاری از طریق افزونه TLS خواهند بود. هرگونه اتصال ورودی به این شنوندگان بدون رمزگذاری TLS، فوراً و بدون ارسال پاسخ خطا به کلاینت بسته خواهد شد.

پشتیبانی از TLS در slurmrestd به نیازمندی‌های افزونه TLS وابسته است. slurmrestd تلاش خواهد کرد تا در هنگام راه‌اندازی، نخستین افزونه در دسترس TLS (به جز tls/none) را به‌طور خودکار بارگذاری کند. نیازمندی‌های هر افزونه در زیر فهرست شده است:

tls/s2n

فایل‌های زیر باید در هنگام راه‌اندازی، موجود و توسط کاربر فراخواننده (پیش از اعمال -u <user id>) قابل خواندن باشند:

متغیرهای محیطی (ENVIRONMENT VARIABLES)

متغیرهای محیطی زیر می‌توانند برای بازنویسی تنظیمات کامپایل‌شده در slurmrestd استفاده شوند.

ABORT_ON_FATAL

هنگامی که خطایی مهلک تشخیص داده می‌شود، به جای exit() از abort() برای خاتمه دادن به فرآیند استفاده می‌کند. این امکان را فراهم می‌سازد که ردگیری پشته (backtrace) بدون نیاز به کامپایل مجدد Slurm ثبت شود.

SLURM_CONF

محل فایل پیکربندی Slurm.

SLURM_DEBUG_FLAGS

مشخص کردن فلگ‌های اشکال‌زدایی برای استفاده توسط slurmrestd. برای فهرست کامل فلگ‌ها، DebugFlags را در صفحه راهنمای slurm.conf(5) ببینید. متغیر محیطی بر تنظیمات درون slurm.conf تقدم دارد.

SLURM_DEBUG

تنظیم صریح سطح اشکال‌زدایی. مقادیر معتبر 0-9 یا مقادیر رشته‌ای مشابه با گزینه‌های اشکال‌زدایی نظیر SlurmctldDebug در slurm.conf(5) هستند. در صورت ارسال -v به عنوان آرگومان در زمان فراخوانی، افزایش می‌یابد. در صورت تنظیم SLURMRESTD_DEBUG، SLURMRESTD_DEBUG_STDERR یا SLURMRESTD_DEBUG_SYSLOG در محیط، نادیده گرفته می‌شود. برای توضیحات مقاصد ثبت گزارش، SLURMRESTD_DEBUG را ببینید.

SLURMRESTD_JSON یا SLURM_JSON

کنترل سریال‌سازی JSON:

SLURM_JWT

این متغیر باید برای استفاده از احراز هویت با توکن JWT تنظیم شود.

SLURMRESTD_AUTH_TYPES

تنظیم انواع مجاز احراز هویت. به -a مراجعه کنید.

SLURMRESTD_DEBUG

تنظیم صریح سطح اشکال‌زدایی. مقادیر معتبر 0-9 یا مقادیر رشته‌ای مشابه با گزینه‌های اشکال‌زدایی نظیر SlurmctldDebug در slurm.conf(5) هستند. اگر یک TTY کنترلی شناسایی شود، حالت تعاملی به‌طور خودکار فعال می‌شود تا اطلاعات گزارش تکمیلی را به stderr ارسال کند. اگر TTY کنترلی شناسایی نشود، گزارش‌ها به syslog ارسال می‌شوند. در صورت ارسال -v به عنوان آرگومان در زمان فراخوانی، افزایش می‌یابد. در صورت تنظیم SLURMRESTD_DEBUG_STDERR یا SLURMRESTD_DEBUG_SYSLOG در محیط، نادیده گرفته می‌شود.

SLURMRESTD_DEBUG_STDERR

تنظیم صریح سطح اشکال‌زدایی برای ثبت گزارش در STDERR. مقادیر معتبر 0-9 یا مقادیر رشته‌ای مشابه با گزینه‌های اشکال‌زدایی نظیر SlurmctldDebug در slurm.conf(5) هستند. در صورت ارسال -v به عنوان آرگومان در زمان فراخوانی، افزایش می‌یابد.

SLURMRESTD_DEBUG_SYSLOG

تنظیم صریح سطح اشکال‌زدایی برای ثبت گزارش در syslog. مقادیر معتبر 0-9 یا مقادیر رشته‌ای مشابه با گزینه‌های اشکال‌زدایی نظیر SlurmctldDebug در slurm.conf(5) هستند. در صورت ارسال -v به عنوان آرگومان در زمان فراخوانی، افزایش می‌یابد.

SLURMRESTD_DATA_PARSER_PLUGINS

فهرست جداشده با کاما از افزونه‌های data_parser برای بارگذاری. به -d مراجعه کنید.

SLURMRESTD_LISTEN

فهرست جداشده با کاما از جفت‌های host:port یا سوکت‌های یونیکس برای شنود.

SLURMRESTD_MAX_CONNECTIONS

تنظیم حداکثر تعداد اتصال‌هایی که در هر لحظه پردازش می‌شوند. به --max-connections مراجعه کنید.

SLURMRESTD_OPENAPI_PLUGINS

فهرست جداشده با کاما از افزونه‌های OpenAPI برای بارگذاری. به -s مراجعه کنید.

SLURMRESTD_RESPONSE_STATUS_CODES

فهرست جداشده با کاما از پاسخ‌های متد OpenAPI جهت تولید در مشخصات OpenAPI. پیش‌فرض: 200,default

SLURMRESTD_SECURITY

کنترل قابلیت‌های امنیتی slurmrestd با استفاده از مقادیر زیر که با کاما جدا شده‌اند:

SLURMRESTD_YAML یا SLURM_YAML

کنترل سریال‌سازی YAML:

سیگنال‌ها (SIGNALS)

SIGINT

slurmrestd به صورت تمیز و ایمن متوقف خواهد شد.

SIGPIPE

این سیگنال صراحتاً نادیده گرفته می‌شود.

SIGPROF

ثبت وضعیت مدیر اتصال در لاگ هنگامی که سطح اشکال‌زدایی حداقل info باشد.

نکات (NOTES)

افزونه‌های SPANK و clifilter به دلیل عدم ایمنی در ریسه‌ها (lack of thread safety) در slurmrestd پشتیبانی نمی‌شوند. افزونه‌های فعال SPANK و JobSubmitPlugins در slurmctld مستقل از slurmrestd هستند و می‌توان از آن‌ها برای اعمال سیاست‌های محلی بر ثبت کارها استفاده کرد.

مثال‌ها (EXAMPLES)

تولید مشخصات OpenAPI بدون نیاز به فایل پیکربندی:

$ slurmrestd -f /dev/null  --generate-openapi-spec -s slurmdbd,slurmctld -d v0.0.42 > openapi.json

راه‌اندازی slurmrestd با یک سوکت یونیکس در حالت شنود:

$ export SLURMRESTD=/var/spool/slurm/restd/rest
$ slurmrestd -s slurmctld,slurmdbd -d v0.0.42 unix:$SLURMRESTD

بررسی برقراری ارتباط با slurmctld از طریق ping، در حالی که slurmrestd در حالت شنود اجرا می‌شود:

$ export $(scontrol token)
$ curl --unix-socket "${SLURMRESTD}" -H "X-SLURM-USER-TOKEN:${SLURM_JWT}" 'http://ignored_with_unix_sockets/slurm/v0.0.42/ping' | jq '.pings'
[
  {
    "hostname": "omicronpersei8",
    "pinged": "UP",
    "latency": 314,
    "mode": "primary"
  }
]

بررسی برقراری ارتباط با slurmdbd با یک درخواست diag، در حالی که slurmrestd در حالت شنود اجرا می‌شود:

$ export $(scontrol token)
$ curl --unix-socket "${SLURMRESTD}" -H "X-SLURM-USER-TOKEN:${SLURM_JWT}" 'http://ignored_with_unix_sockets/slurmdb/v0.0.42/diag' | jq '.pings'
1722009793

استعلام وضعیت یک گره در حالی که slurmrestd در حالت INETD اجرا می‌شود:

$ echo -e "GET http://ignored/slurm/v0.0.42/node/host1 HTTP/1.1\r\n" | slurmrestd
HTTP/1.1 200 OK
Content-Length: 3174
Content-Type: application/json
{
  "nodes": [
    {
      "architecture": "x86_64",
      "burstbuffer_network_address": "",
      "boards": 1,
      "boot_time": {
        "set": true,
        "infinite": false,
	"number": 1720820315
      },
      "cluster_name": "",
      "cores": 16,
      "specialized_cores": 0,
      "cpu_binding": 0,
      "cpu_load": 446,
      "free_mem": {
        "set": true,
        "infinite": false,
	"number": 39871
      },
      "cpus": 32,
      "effective_cpus": 32,
      "specialized_cpus": "",
      "energy": {
        "average_watts": 0,
        "base_consumed_energy": 0,
        "consumed_energy": 0,
	"current_watts": {
          "set": false,
          "infinite": false,
          "number": 0
        },
	"previous_consumed_energy": 0,
	"last_collected": 0
      },
      "external_sensors": {},
      "extra": "",
      "power": {},
      "features": [],
      "active_features": [],
      "gpu_spec": "",
      "gres": "gpu:fake1:1(S:0),gpu:fake2:1(S:0)",
      "gres_drained": "NA",
      "gres_used": "gpu:fake1:0(IDX:NA),gpu:fake2:0(IDX:NA)",
      "instance_id": "",
      "instance_type": "",
      "last_busy": {
	"set": true,
	"infinite": false,
	"number": 1722009794
      },
      "mcs_label": "",
      "specialized_memory": 0,
      "name": "host1",
      "next_state_after_reboot": [
	"INVALID"
      ],
      "address": "localhost",
      "hostname": "omicronpersei8",
      "state": [
        "IDLE"
      ],
      "operating_system": "Linux 6.5.0-44-generic #44-Ubuntu SMP PREEMPT_DYNAMIC Fri Jun  7 15:10:09 UTC 2024",
      "owner": "",
      "partitions": [
        "debug"
      ],
      "port": 5015,
      "real_memory": 127927,
      "res_cores_per_gpu": 0,
      "comment": "",
      "reason": "",
      "reason_changed_at": {
	"set": true,
	"infinite": false,
	"number": 0
      },
      "reason_set_by_user": "",
      "resume_after": {
        "set": true,
        "infinite": false,
        "number": 0
      },
      "reservation": "",
      "alloc_memory": 0,
      "alloc_cpus": 0,
      "alloc_idle_cpus": 32,
      "tres_used": "",
      "tres_weighted": 0.0,
      "slurmd_start_time": {
	"set": true,
	"infinite": false,
	"number": 1722009794
      },
      "sockets": 1,
      "threads": 2,
      "temporary_disk": 0,
      "weight": 1,
      "tres": "cpu=32,mem=127927M,billing=32,gresgpu=2",
      "version": "24.11.0-0rc1"
    }
  ],
  "last_update": {
    "set": true,
    "infinite": false,
    "number": 1722010273
  },
  "meta": {
<<< TRIMMED >>>
  },
  "errors": [],
  "warnings": []
}

ارسال یک کار (job) به slurmrestd در حالی که در حالت شنود اجرا می‌شود:

$ jq . example_job.json
{
  "job": {
    "script": "#!/bin/bash\nsleep 30",
    "name": "ExampleJob",
    "account": "sub1",
    "environment": [
      "PATH=/usr/bin/:/bin/"
    ],
    "current_working_directory": "/tmp/",
    "tasks": 12,
    "memory_per_cpu": 100,
    "time_limit": 240
  }
}
$ curl -H "Content-Type: application/json" --data-binary @example_job.json --unix-socket "${SLURMRESTD}" 'http://ignored/slurm/v0.0.42/job/submit'
{
  "job_id": 9,
  "step_id": "batch",
  "job_submit_user_msg": "",
  "meta": {
<<< TRIMMED >>>
  },
  "errors": [],
  "warnings": []
}
$ curl -H "Content-Type: application/json" --data-binary @example_job.json --unix-socket "${SLURMRESTD}" 'http://ignored/slurm/v0.0.42/job/submit'
{
  "job_id": 7,
  "step_id": "batch",
  "job_submit_user_msg": "",
  "meta": {
  },
  "errors": [],
  "warnings": [
    {
      "description": "Expected OpenAPI type=array (Slurm type=list) but got OpenAPI type=object (Slurm type=dictionary): {
      "source": "#jobenvironment"
    }
  ]
}

کپی‌رایت (COPYING)

Copyright (C) 2019-2022 SchedMD LLC.

این فایل بخشی از Slurm است که یک برنامه مدیریت منابع می‌باشد. برای جزئیات بیشتر، به https://slurm.schedmd.com مراجعه کنید.

نرم‌افزار Slurm یک نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط «مجوز عمومی همگانی گنو» (GNU General Public License) همان‌طور که توسط «بنیاد نرم‌افزارهای آزاد» منتشر شده است، چه نسخه ۲ مجوز و چه (به انتخاب خودتان) هر نسخه بعدی، بازتوزیع کرده و/یا تغییر دهید.

توزیع Slurm به این امید انجام شده است که مفید واقع شود، اما بدون هرگونه ضمانت؛ حتی بدون ضمانت ضمنی قابل فروش بودن یا مناسب بودن برای یک هدف مشخص. برای جزئیات بیشتر به «مجوز عمومی همگانی گنو» مراجعه کنید.

همچنین ببینید (SEE ALSO)

slurm.conf(5), slurmctld(8), slurmdbd(8)