نام (NAME)

org.freedesktop.hostname1 - رابط کاربری D-Bus سرویس systemd-hostnamed

توضیحات (DESCRIPTION)

systemd-hostnamed.service(8) یک سرویس سیستمی است که می‌تواند برای کنترل نام میزبان و متادیتای مرتبط با ماشین از طریق برنامه‌های کاربردی استفاده شود. این صفحه معانی و مفاهیم نام میزبان و رابط D-Bus را شرح می‌دهد.

رابط D-BUS (THE D-BUS INTERFACE)

این سرویس رابط‌های زیر را در گذرگاه ارائه می‌دهد:

node /org/freedesktop/hostname1 {
  interface org.freedesktop.hostname1 {
    methods:
      SetHostname(in  s hostname,
                  in  b interactive);
      SetStaticHostname(in  s hostname,
                        in  b interactive);
      SetPrettyHostname(in  s hostname,
                        in  b interactive);
      SetIconName(in  s icon,
                  in  b interactive);
      SetChassis(in  s chassis,
                 in  b interactive);
      SetDeployment(in  s deployment,
                    in  b interactive);
      SetLocation(in  s location,
                  in  b interactive);
      SetTags(in  as tags);
      GetProductUUID(in  b interactive,
                     out ay uuid);
      GetHardwareSerial(out s serial);
      Describe(out s json);
      GetMachineInfo(in  s field,
                     out s value);
    properties:
      readonly s Hostname = '...';
      readonly s StaticHostname = '...';
      readonly s PrettyHostname = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s DefaultHostname = '...';
      readonly s HostnameSource = '...';
      readonly s IconName = '...';
      readonly s Chassis = '...';
      readonly s Deployment = '...';
      readonly s Location = '...';
      readonly as Tags = ['...', ...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s KernelName = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s KernelRelease = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s KernelVersion = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s OperatingSystemPrettyName = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s OperatingSystemFancyName = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s OperatingSystemCPEName = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly t OperatingSystemSupportEnd = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s HomeURL = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s OperatingSystemImageID = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s OperatingSystemImageVersion = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s HardwareVendor = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s HardwareModel = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s HardwareSKU = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s HardwareVersion = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s FirmwareVersion = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s FirmwareVendor = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly t FirmwareDate = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly ay MachineID = [...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly ay BootID = [...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly u VSockCID = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s ChassisAssetTag = '...';
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
};

هر زمان که نام میزبان یا سایر متاداده‌ها از طریق دیمن تغییر کند، سیگنال‌های PropertyChanged به کلاینت‌های مشترک‌شده ارسال می‌شوند. تغییر نام میزبان با استفاده از این رابط از طریق polkit[1] احراز هویت می‌شود.

مفاهیم و معانی (SEMANTICS)

ویژگی StaticHostname نام میزبان «ایستا» (static) پیکربندی‌شده در /etc/hostname را ارائه می‌دهد. این ویژگی همیشه با نام میزبان فعلی که توسط فراخوانی سیستمی gethostname(3) برگردانده می‌شود همگام نیست. اگر هیچ نام میزبان ایستایی پیکربندی نشده باشد، این ویژگی یک رشته خالی خواهد بود.

هنگامی که systemd(1) یا systemd-hostnamed.service(8) نام میزبان را تنظیم می‌کنند، این نام میزبان ایستا بالاترین اولویت را دارد.

ویژگی Hostname نام میزبان واقعی پیکربندی‌شده در هسته از طریق sethostname(2) را نشان می‌دهد. این مقدار می‌تواند با نام میزبان ایستا متفاوت باشد. این ویژگی هرگز خالی نیست.

ویژگی PrettyHostname «نام میزبان خوانا» (pretty hostname) را نشان می‌دهد که یک نام میزبان آزاد در قالب UTF-8 برای نمایش به کاربر است. رابط‌های کاربری باید اطمینان حاصل کنند که نام میزبان خوانا و نام میزبان ایستا همگام باقی بمانند؛ به عنوان مثال، هنگامی که نام اول "Lennart’s Computer" باشد، نام دوم باید "lennarts-computer" باشد. اگر هیچ نام میزبان خوانایی تنظیم نشده باشد، این تنظیم یک رشته خالی خواهد بود. در این حالت برنامه‌ها باید یک جایگزین مناسب (مانند نام میزبان پویا) بیابند.

ویژگی DefaultHostname نام میزبان پیش‌فرض (پیکربندی‌شده از طریق os-release(5) یا یک مقدار جایگزین تعیین‌شده در زمان کامپایل) را نشان می‌دهد.

ویژگی HostnameSource منشأ نام میزبان پیکربندی‌شده فعلی را نشان می‌دهد؛ یکی از مقادیر "static" (تنظیم‌شده از /etc/hostname)، "transient" (یک نام میزبان غیردائمی از یک منبع خارجی)، "default" (مقدار حاصل از os-release یا مقدار جایگزین در زمان کامپایل).

ویژگی IconName «نام آیکون» (icon name) را مطابق با مشخصات نام‌گذاری آیکون XDG نشان می‌دهد. در صورت تنظیم نشدن، اطلاعاتی مانند نوع شاسی (در زیر ببینید) برای یافتن نام آیکون جایگزین مناسب استفاده می‌شود (به عنوان مثال، انتخاب "computer-laptop" در برابر "computer-desktop" بر اساس اطلاعات شاسی انجام می‌گیرد). اگر چنین داده‌ای در دسترس نباشد، رشته خالی برگردانده می‌شود. در این حالت یک برنامه کاربردی باید به یک آیکون جایگزین، مثلاً "computer" رجوع کند. اگر این ویژگی روی رشته خالی تنظیم شود، انتخاب خودکار نام جایگزین مجدداً فعال می‌شود.

ویژگی Chassis یک «نوع شاسی» (chassis type) را نشان می‌دهد که یکی از انواع شاسی تعریف‌شده فعلی است: "desktop", "laptop", "server", "tablet", "handset", و همچنین انواع شاسی ویژه "vm" و "container" برای سیستم‌های مجازی‌سازی‌شده. توجه داشته باشید که در بیشتر موارد نوع شاسی به طور خودکار از اطلاعات سفت‌افزار DMI/SMBIOS/ACPI تشخیص داده می‌شود. بنابراین، نوشتن در این تنظیم تنها برای لغو انواع شاسی اشتباه‌تشخیص‌داده‌شده، یا پیکربندی نوع شاسی در صورتی که به طور خودکار قابل تشخیص نباشد، مفید است. برای فعال‌سازی مجدد تشخیص خودکار نوع شاسی از اطلاعات سفت‌افزار، این ویژگی را روی یک رشته خالی تنظیم کنید.

ویژگی Tags فهرستی از «برچسب‌های ماشین» (machine tags) را نشان می‌دهد: برچسب‌های کوتاهی که می‌توانند برای طبقه‌بندی و گروه‌بندی ماشین‌ها با اهداف مدیریتی استفاده شوند، به عنوان مثال برای شناسایی نقشی که یک ماشین در استقرار ایفا می‌کند، ناوگان یا واحد سازمانی که به آن تعلق دارد، یا هر ویژگی تعریف‌شده دیگری توسط مدیر سیستم. هر برچسب تکی بین ۱ تا ۲۵۵ کاراکتر طول دارد و فقط شامل حروف و اعداد اسکی (ASCII)، "-" و "." است. این برچسب‌ها به صورت یک فهرست جداشده با دونقطه در فیلد TAGS= فایل /etc/machine-info ذخیره می‌شوند؛ برای جزئیات به machine-info(5) مراجعه کنید. اگر هیچ برچسبی پیکربندی نشده باشد، این ویژگی یک فهرست خالی است.

توجه داشته باشید که systemd-hostnamed تنها بنا به درخواست شروع به کار کرده و پس از مدت کوتاهی بی‌کاری خاتمه می‌یابد. این عملاً به این معنی است که پیام‌های PropertyChanged برای تغییراتی که مستقیماً در فایل‌ها اعمال می‌شوند (مانند ویرایش فایل‌ها توسط مدیر با vi) ارسال نمی‌شوند. این رفتار مورد انتظار است: تغییرات دستی پیکربندی باید نیاز به بازخوانی دستی داشته باشند.

نام میزبان گذرا (پویا) که توسط ویژگی Hostname ارائه می‌شود مستقیماً به نام میزبان هسته نگاشت می‌شود. باید فرض شود که این نام میزبان بسیار پویا است و بنابراین باید مستقیماً بدون وابستگی به پیام‌های PropertyChanged از systemd-hostnamed پایش شود. برای انجام این کار، /proc/sys/kernel/hostname را باز کرده و برای SIGHUP که هر بار با تغییر نام میزبان توسط هسته برانگیخته می‌شود، poll(3) کنید. باز هم تأکید می‌شود: این موضوع ویژه نام میزبان گذرا (پویا) است و برای نام میزبان پیکربندی‌شده (ثابت) صدق نمی‌کند.

در صورتی که اعلان‌های تغییر نام میزبان ضروری نباشد، برنامه‌ها می‌توانند داده‌های نام میزبان را مستقیماً بخوانند. برای این منظور از gethostname(2)، /etc/hostname (احتمالاً همراه با گزینه‌های جایگزین متناسب با توزیع) و machine-info(5) استفاده کنید. برای اطلاعات بیشتر درباره این فایل‌ها و فراخوانی‌های سیستمی به صفحات راهنمای مربوطه مراجعه فرمایید.

ویژگی‌های KernelName، KernelRelease و KernelVersion نام هسته (مثلاً "Linux")، شماره انتشار (مثلاً "5.0.0-11") و نسخه (یعنی شماره ساخت، مثلاً "#11") را طبق گزارش uname(2) ارائه می‌دهند.

ویژگی‌های OperatingSystemPrettyName، OperatingSystemFancyName، OperatingSystemCPEName و HomeURL فیلدهای PRETTY_NAME=، FANCY_NAME=، CPE_NAME= و HOME_URL= را از فایل os-release(5) ارائه می‌دهند. هدف از این ویژگی‌ها این است که به کلاینت‌های راه دور امکان دسترسی به این اطلاعات را از طریق D-Bus بدهند. کلاینت‌های محلی می‌توانند مستقیماً به این اطلاعات دسترسی داشته باشند.

ویژگی MachineID شناسه ماشین ۱۲۸ بیتی را ارائه می‌دهد؛ برای جزئیات به machine-id(5) مراجعه کنید.

ویژگی BootID شناسه بوت ۱۲۸ بیتی را طبق /proc/sys/kernel/random/boot_id ارائه می‌دهد.

ویژگی VSockCID شناسه کانتکست (CID، یعنی آدرس) محلی AF_VSOCK سیستم را در صورت در دسترس بودن در محیط ماشین مجازی نشان می‌دهد. در غیر این صورت روی UINT32_MAX تنظیم می‌شود. برای جزئیات به vsock(7) مراجعه کنید.

ویژگی OperatingSystemSupportEnd زمان پایان پشتیبانی ارائه‌دهنده سیستم‌عامل را در صورت مشخص بودن این اطلاعات ارائه می‌دهد. این مقدار یک عدد بدون علامت ۶۴ بیتی بر حسب میکروثانیه (µs) از مبدأ زمان یونیکس (UNIX epoch) در ساعت UTC است. اگر این اطلاعات مشخص نباشد، حاوی مقدار 2^64-1 یعنی UINT64_MAX خواهد بود.

ویژگی‌های OperatingSystemImageID و OperatingSystemImageVersion نام و نسخه ایمیج سیستم‌عامل را در صورت در دسترس بودن ارائه می‌دهند و در غیر این صورت حاوی رشته‌های خالی هستند. این موارد غالباً با فیلدهای IMAGE_ID= و IMAGE_VERSION= در فایل os-release مطابقت دارند.

ویژگی‌های HardwareVendor، HardwareModel، HardwareSKU و HardwareVersion اطلاعات سازنده درباره سخت‌افزار سیستم را ارائه می‌دهند. واحد نگهداری موجودی (SKU) نوع مشخصی از سخت‌افزار را برای فروش، خرید یا مدیریت موجودی توصیف می‌کند. فیلدهای SKU و نسخه تنها در صورتی در دسترس هستند که با مدل و با یکدیگر تفاوت داشته باشند. به این ترتیب نسخه خاص‌تر بوده و فقط در صورتی موجود است که با مدل و SKU تفاوت داشته باشد. اگر چنین اطلاعاتی قابل تعیین نباشد، این ویژگی‌ها روی رشته‌های خالی تنظیم می‌شوند.

ویژگی‌های FirmwareVersion و FirmwareVendor اطلاعاتی درباره سفت‌افزار سیستم، یعنی یک رشته نسخه و نام سازنده را ارائه می‌دهند. اگر چنین اطلاعاتی قابل تعیین نباشد، این ویژگی‌ها روی رشته‌های خالی تنظیم می‌شوند.

ویژگی FirmwareDate تاریخ ساخت سفت‌افزار را در صورت مشخص بودن نشان می‌دهد. این مقدار یک عدد بدون علامت ۶۴ بیتی بر حسب میکروثانیه (µs) از مبدأ زمان یونیکس (UNIX epoch) در ساعت UTC است. در صورت نامشخص بودن، مقدار آن UNIT64_MAX است.

ویژگی ChassisAssetTag یک شناسه منحصربه‌فرد از برچسب اموال شاسی سیستم را ارائه می‌دهد. اگر این اطلاعات مشخص نباشد، این ویژگی روی یک رشته خالی تنظیم می‌شود.

توصیه‌ها (RECOMMENDATIONS)

در اینجا سه مثال آورده شده است که نحوه استفاده از نام میزبان خوانا و نام آیکون را نشان می‌دهند:

برای مدیریت صحیح جستجوی نام با تغییر نام‌های میزبان محلی بدون نیاز به ویرایش /etc/hosts، توصیه می‌کنیم از systemd-hostnamed همراه با nss-myhostname(8) استفاده کنید.

در ادامه توصیه‌هایی برای تولید یک نام میزبان ایستا (اینترنتی) از روی یک نام خوانا آورده شده است:

توجه داشته باشید اگرچه systemd-hostnamed برخی بررسی‌ها را روی نام میزبان ارسال‌شده اعمال می‌کند، اما این بررسی‌ها بسیار سهل‌گیرانه‌تر از توصیه‌های فوق هستند. به عنوان مثال، systemd-hostnamed نویسه "_" را نیز در نام میزبان می‌پذیرد، اما برای جلوگیری از تداخل با انواع سرویس‌های DNS-SD توصیه می‌کنیم از آن استفاده نکنید. همچنین systemd-hostnamed نام‌های میزبان طولانی‌تر را نیز مجاز می‌داند، اما با توجه به محدودیت‌های برچسب DNS، توصیه می‌کنیم از آن بهره نگیرید.

در اینجا چند نمونه از این تبدیل‌ها آورده شده است:

البته، یک برچسب نام میزبان اینترنتی که از قبل معتبر است و آن را وارد کرده و از این تبدیل عبور می‌دهید، باید دست‌نخورده باقی بماند، تا کاربران در صورت تمایل کنترل مستقیمی بر آن داشته باشند — با نادیده گرفتن این واقعیت که نام میزبان خوانا یک نام زیبا است و صرفاً ویرایش آن به گونه‌ای که گویی نام عادی اینترنتی است.

مثال‌ها (EXAMPLES)

مثال ۱. درون‌نگری org.freedesktop.hostname1 روی گذرگاه

$ gdbus introspect --system \
  --dest org.freedesktop.hostname1 \
  --object-path /org/freedesktop/hostname1

سازگاری نسخه (VERSION COMPATIBILITY)

این رابط‌های D-Bus از دستورالعمل‌های معمول نسخه‌بندی رابط[2] پیروی می‌کنند.

تاریخچه (HISTORY)

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

systemd(1), systemd-hostnamed.service(8), hostnamectl(1), صفحه ویژگی اولیه دیوید زوتن در فدورا درباره xdg-hostname[3]

نکات (NOTES)

1.

polkit

2.

دستورالعمل‌های معمول نسخه‌بندی رابط

3.

صفحه ویژگی درباره xdg-hostname