'\" t
.TH "ORG\&.FREEDESKTOP\&.HOSTNAME1" "5" "" "systemd 261.2" "org.freedesktop.hostname1"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "نام (NAME)"
org.freedesktop.hostname1 \- رابط کاربری D-Bus سرویس systemd-hostnamed
.SH "توضیحات (DESCRIPTION)"
.PP
\fBsystemd-hostnamed.service\fR(8)
یک سرویس سیستمی است که می‌تواند برای کنترل نام میزبان و متادیتای مرتبط با ماشین از طریق برنامه‌های کاربردی استفاده شود\&. این صفحه معانی و مفاهیم نام میزبان و رابط D\-Bus را شرح می‌دهد\&.
.SH "رابط D-BUS (THE D-BUS INTERFACE)"
.PP
این سرویس رابط‌های زیر را در گذرگاه ارائه می‌دهد:
.sp
.if n \{\
.RS 4
.\}
.nf
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 = \*(Aq\&.\&.\&.\*(Aq;
      readonly s StaticHostname = \*(Aq\&.\&.\&.\*(Aq;
      readonly s PrettyHostname = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s DefaultHostname = \*(Aq\&.\&.\&.\*(Aq;
      readonly s HostnameSource = \*(Aq\&.\&.\&.\*(Aq;
      readonly s IconName = \*(Aq\&.\&.\&.\*(Aq;
      readonly s Chassis = \*(Aq\&.\&.\&.\*(Aq;
      readonly s Deployment = \*(Aq\&.\&.\&.\*(Aq;
      readonly s Location = \*(Aq\&.\&.\&.\*(Aq;
      readonly as Tags = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.];
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s KernelName = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s KernelRelease = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s KernelVersion = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s OperatingSystemPrettyName = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s OperatingSystemFancyName = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s OperatingSystemCPEName = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly t OperatingSystemSupportEnd = \&.\&.\&.;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s HomeURL = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s OperatingSystemImageID = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s OperatingSystemImageVersion = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s HardwareVendor = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s HardwareModel = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s HardwareSKU = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s HardwareVersion = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s FirmwareVersion = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s FirmwareVendor = \*(Aq\&.\&.\&.\*(Aq;
      @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 = \*(Aq\&.\&.\&.\*(Aq;
  };
  interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
  interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
  interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
};
.fi
.if n \{\
.RE
.\}
.sp
.PP
هر زمان که نام میزبان یا سایر متاداده‌ها از طریق دیمن تغییر کند، سیگنال‌های
\fBPropertyChanged\fR
به کلاینت‌های مشترک‌شده ارسال می‌شوند\&. تغییر نام میزبان با استفاده از این رابط از طریق
\m[blue]\fBpolkit\fR\m[]\&\s-2\u[1]\d\s+2
احراز هویت می‌شود\&.
.SH "مفاهیم و معانی (SEMANTICS)"
.PP
ویژگی
\fIStaticHostname\fR
نام میزبان «ایستا» (static) پیکربندی‌شده در
/etc/hostname
را ارائه می‌دهد\&. این ویژگی همیشه با نام میزبان فعلی که توسط فراخوانی سیستمی
\fBgethostname\fR(3)
برگردانده می‌شود همگام نیست\&. اگر هیچ نام میزبان ایستایی پیکربندی نشده باشد، این ویژگی یک رشته خالی خواهد بود\&.
.PP
هنگامی که
\fBsystemd\fR(1)
یا
\fBsystemd-hostnamed.service\fR(8)
نام میزبان را تنظیم می‌کنند، این نام میزبان ایستا
\fIبالاترین اولویت را دارد\fR\&.
.PP
ویژگی
\fIHostname\fR
نام میزبان واقعی پیکربندی‌شده در هسته از طریق
\fBsethostname\fR(2)
را نشان می‌دهد\&. این مقدار می‌تواند با نام میزبان ایستا متفاوت باشد\&. این ویژگی هرگز خالی نیست\&.
.PP
ویژگی
\fIPrettyHostname\fR
«نام میزبان خوانا» (pretty hostname) را نشان می‌دهد که یک نام میزبان آزاد در قالب UTF\-8 برای نمایش به کاربر است\&. رابط‌های کاربری باید اطمینان حاصل کنند که نام میزبان خوانا و نام میزبان ایستا همگام باقی بمانند؛ به عنوان مثال، هنگامی که نام اول
"Lennart\(cqs Computer"
باشد، نام دوم باید
"lennarts\-computer"
باشد\&. اگر هیچ نام میزبان خوانایی تنظیم نشده باشد، این تنظیم یک رشته خالی خواهد بود\&. در این حالت برنامه‌ها باید یک جایگزین مناسب (مانند نام میزبان پویا) بیابند\&.
.PP
ویژگی
\fIDefaultHostname\fR
نام میزبان پیش‌فرض (پیکربندی‌شده از طریق
\fBos-release\fR(5)
یا یک مقدار جایگزین تعیین‌شده در زمان کامپایل) را نشان می‌دهد\&.
.PP
ویژگی
\fIHostnameSource\fR
منشأ نام میزبان پیکربندی‌شده فعلی را نشان می‌دهد؛ یکی از مقادیر
"static"
(تنظیم‌شده از
/etc/hostname)،
"transient"
(یک نام میزبان غیردائمی از یک منبع خارجی)،
"default"
(مقدار حاصل از
os\-release
یا مقدار جایگزین در زمان کامپایل)\&.
.PP
ویژگی
\fIIconName\fR
«نام آیکون» (icon name) را مطابق با مشخصات نام‌گذاری آیکون XDG نشان می‌دهد\&. در صورت تنظیم نشدن، اطلاعاتی مانند نوع شاسی (در زیر ببینید) برای یافتن نام آیکون جایگزین مناسب استفاده می‌شود (به عنوان مثال، انتخاب
"computer\-laptop"
در برابر
"computer\-desktop"
بر اساس اطلاعات شاسی انجام می‌گیرد)\&. اگر چنین داده‌ای در دسترس نباشد، رشته خالی برگردانده می‌شود\&. در این حالت یک برنامه کاربردی باید به یک آیکون جایگزین، مثلاً
"computer"
رجوع کند\&. اگر این ویژگی روی رشته خالی تنظیم شود، انتخاب خودکار نام جایگزین مجدداً فعال می‌شود\&.
.PP
ویژگی
\fIChassis\fR
یک «نوع شاسی» (chassis type) را نشان می‌دهد که یکی از انواع شاسی تعریف‌شده فعلی است:
"desktop",
"laptop",
"server",
"tablet",
"handset",
و همچنین انواع شاسی ویژه
"vm"
و
"container"
برای سیستم‌های مجازی‌سازی‌شده\&. توجه داشته باشید که در بیشتر موارد نوع شاسی به طور خودکار از اطلاعات سفت‌افزار DMI/SMBIOS/ACPI تشخیص داده می‌شود\&. بنابراین، نوشتن در این تنظیم تنها برای لغو انواع شاسی اشتباه‌تشخیص‌داده‌شده، یا پیکربندی نوع شاسی در صورتی که به طور خودکار قابل تشخیص نباشد، مفید است\&. برای فعال‌سازی مجدد تشخیص خودکار نوع شاسی از اطلاعات سفت‌افزار، این ویژگی را روی یک رشته خالی تنظیم کنید\&.
.PP
ویژگی
\fITags\fR
فهرستی از «برچسب‌های ماشین» (machine tags) را نشان می‌دهد: برچسب‌های کوتاهی که می‌توانند برای طبقه‌بندی و گروه‌بندی ماشین‌ها با اهداف مدیریتی استفاده شوند، به عنوان مثال برای شناسایی نقشی که یک ماشین در استقرار ایفا می‌کند، ناوگان یا واحد سازمانی که به آن تعلق دارد، یا هر ویژگی تعریف‌شده دیگری توسط مدیر سیستم\&. هر برچسب تکی بین ۱ تا ۲۵۵ کاراکتر طول دارد و فقط شامل حروف و اعداد اسکی (ASCII)،
"\-"
و
"\&."
است\&. این برچسب‌ها به صورت یک فهرست جداشده با دونقطه در فیلد
\fITAGS=\fR
فایل
/etc/machine\-info
ذخیره می‌شوند؛ برای جزئیات به
\fBmachine-info\fR(5)
مراجعه کنید\&. اگر هیچ برچسبی پیکربندی نشده باشد، این ویژگی یک فهرست خالی است\&.
.PP
توجه داشته باشید که
systemd\-hostnamed
تنها بنا به درخواست شروع به کار کرده و پس از مدت کوتاهی بی‌کاری خاتمه می‌یابد\&. این عملاً به این معنی است که پیام‌های
\fBPropertyChanged\fR
برای تغییراتی که مستقیماً در فایل‌ها اعمال می‌شوند (مانند ویرایش فایل‌ها توسط مدیر با vi) ارسال نمی‌شوند\&. این رفتار مورد انتظار است: تغییرات دستی پیکربندی باید نیاز به بازخوانی دستی داشته باشند\&.
.PP
نام میزبان گذرا (پویا) که توسط ویژگی
\fIHostname\fR
ارائه می‌شود مستقیماً به نام میزبان هسته نگاشت می‌شود\&. باید فرض شود که این نام میزبان بسیار پویا است و بنابراین باید مستقیماً بدون وابستگی به پیام‌های
\fBPropertyChanged\fR
از
systemd\-hostnamed
پایش شود\&. برای انجام این کار،
/proc/sys/kernel/hostname
را باز کرده و برای
\fBSIGHUP\fR
که هر بار با تغییر نام میزبان توسط هسته برانگیخته می‌شود،
\fBpoll\fR(3)
کنید\&. باز هم تأکید می‌شود: این موضوع ویژه نام میزبان گذرا (پویا) است و برای نام میزبان پیکربندی‌شده (ثابت) صدق نمی‌کند\&.
.PP
در صورتی که اعلان‌های تغییر نام میزبان ضروری نباشد، برنامه‌ها می‌توانند داده‌های نام میزبان را مستقیماً بخوانند\&. برای این منظور از
\fBgethostname\fR(2)،
/etc/hostname
(احتمالاً همراه با گزینه‌های جایگزین متناسب با توزیع) و
\fBmachine-info\fR(5)
استفاده کنید\&. برای اطلاعات بیشتر درباره این فایل‌ها و فراخوانی‌های سیستمی به صفحات راهنمای مربوطه مراجعه فرمایید\&.
.PP
ویژگی‌های
\fIKernelName\fR،
\fIKernelRelease\fR
و
\fIKernelVersion\fR
نام هسته (مثلاً
"Linux")،
شماره انتشار (مثلاً
"5\&.0\&.0\-11")
و نسخه (یعنی شماره ساخت، مثلاً
"#11")
را طبق گزارش
\fBuname\fR(2)
ارائه می‌دهند\&.
.PP
ویژگی‌های
\fIOperatingSystemPrettyName\fR،
\fIOperatingSystemFancyName\fR،
\fIOperatingSystemCPEName\fR
و
\fIHomeURL\fR
فیلدهای
\fIPRETTY_NAME=\fR،
\fIFANCY_NAME=\fR،
\fICPE_NAME=\fR
و
\fIHOME_URL=\fR
را از فایل
\fBos-release\fR(5)
ارائه می‌دهند\&. هدف از این ویژگی‌ها این است که به کلاینت‌های راه دور امکان دسترسی به این اطلاعات را از طریق D\-Bus بدهند\&. کلاینت‌های محلی می‌توانند مستقیماً به این اطلاعات دسترسی داشته باشند\&.
.PP
ویژگی
\fIMachineID\fR
شناسه ماشین ۱۲۸ بیتی را ارائه می‌دهد؛ برای جزئیات به
\fBmachine-id\fR(5)
مراجعه کنید\&.
.PP
ویژگی
\fIBootID\fR
شناسه بوت ۱۲۸ بیتی را طبق
/proc/sys/kernel/random/boot_id
ارائه می‌دهد\&.
.PP
ویژگی
\fIVSockCID\fR
شناسه کانتکست (CID، یعنی آدرس) محلی
\fBAF_VSOCK\fR
سیستم را در صورت در دسترس بودن در محیط ماشین مجازی نشان می‌دهد\&. در غیر این صورت روی
\fBUINT32_MAX\fR
تنظیم می‌شود\&. برای جزئیات به
\fBvsock\fR(7)
مراجعه کنید\&.
.PP
ویژگی
\fIOperatingSystemSupportEnd\fR
زمان پایان پشتیبانی ارائه‌دهنده سیستم‌عامل را در صورت مشخص بودن این اطلاعات ارائه می‌دهد\&. این مقدار یک عدد بدون علامت ۶۴ بیتی بر حسب میکروثانیه (\(mcs) از مبدأ زمان یونیکس (UNIX epoch) در ساعت UTC است\&. اگر این اطلاعات مشخص نباشد، حاوی مقدار 2^64\-1 یعنی
\fBUINT64_MAX\fR
خواهد بود\&.
.PP
ویژگی‌های
\fIOperatingSystemImageID\fR
و
\fIOperatingSystemImageVersion\fR
نام و نسخه ایمیج سیستم‌عامل را در صورت در دسترس بودن ارائه می‌دهند و در غیر این صورت حاوی رشته‌های خالی هستند\&. این موارد غالباً با فیلدهای
\fIIMAGE_ID=\fR
و
\fIIMAGE_VERSION=\fR
در فایل
os\-release
مطابقت دارند\&.
.PP
ویژگی‌های
\fIHardwareVendor\fR،
\fIHardwareModel\fR،
\fIHardwareSKU\fR
و
\fIHardwareVersion\fR
اطلاعات سازنده درباره سخت‌افزار سیستم را ارائه می‌دهند\&. واحد نگهداری موجودی (SKU) نوع مشخصی از سخت‌افزار را برای فروش، خرید یا مدیریت موجودی توصیف می‌کند\&. فیلدهای SKU و نسخه تنها در صورتی در دسترس هستند که با مدل و با یکدیگر تفاوت داشته باشند\&. به این ترتیب نسخه خاص‌تر بوده و فقط در صورتی موجود است که با مدل و SKU تفاوت داشته باشد\&. اگر چنین اطلاعاتی قابل تعیین نباشد، این ویژگی‌ها روی رشته‌های خالی تنظیم می‌شوند\&.
.PP
ویژگی‌های
\fIFirmwareVersion\fR
و
\fIFirmwareVendor\fR
اطلاعاتی درباره سفت‌افزار سیستم، یعنی یک رشته نسخه و نام سازنده را ارائه می‌دهند\&. اگر چنین اطلاعاتی قابل تعیین نباشد، این ویژگی‌ها روی رشته‌های خالی تنظیم می‌شوند\&.
.PP
ویژگی
\fIFirmwareDate\fR
تاریخ ساخت سفت‌افزار را در صورت مشخص بودن نشان می‌دهد\&. این مقدار یک عدد بدون علامت ۶۴ بیتی بر حسب میکروثانیه (\(mcs) از مبدأ زمان یونیکس (UNIX epoch) در ساعت UTC است\&. در صورت نامشخص بودن، مقدار آن
\fBUNIT64_MAX\fR
است\&.
.PP
ویژگی
\fIChassisAssetTag\fR
یک شناسه منحصربه‌فرد از برچسب اموال شاسی سیستم را ارائه می‌دهد\&. اگر این اطلاعات مشخص نباشد، این ویژگی روی یک رشته خالی تنظیم می‌شود\&.
.SS "متدها (Methods)"
.PP
متد
\fBSetHostname()\fR
نام میزبان گذرا (پویا) را تنظیم می‌کند، که در صورت تعیین نشدن نام میزبان ایستا استفاده می‌شود\&. این مقدار باید یک نام میزبان به سبک اینترنتی، شامل حروف اسکی (ASCII) کوچک ۷ بیتی، بدون نویسه‌های خاص یا فاصله باشد\&. یک رشته خالی نام میزبان گذرا را پاک خواهد کرد\&.
.PP
متد
\fBSetStaticHostname()\fR
نام میزبان ایستا را که توسط ویژگی
\fIStaticHostname\fR
ارائه می‌شود تنظیم می‌کند\&. هنگامی که با یک آرگومان خالی فراخوانی شود، پیکربندی ایستا در
/etc/hostname
حذف می‌گردد\&. از آنجا که نام میزبان ایستا بالاترین اولویت را دارد، فراخوانی این تابع معمولاً بر ویژگی
\fIHostname\fR
و نام میزبان مؤثر پیکربندی‌شده در هسته نیز تأثیر می‌گذارد\&.
.PP
متد
\fBSetPrettyHostname()\fR
نام میزبان خوانا را که توسط ویژگی
\fIPrettyHostname\fR
ارائه می‌شود تنظیم می‌کند\&.
.PP
متدهای
\fBSetIconName()\fR،
\fBSetChassis()\fR،
\fBSetDeployment()\fR
و
\fBSetLocation()\fR
به ترتیب ویژگی‌های
\fIIconName\fR
(نام آیکون معرف ماشین)،
\fIChassis\fR
(فرم فاکتور یا شکل ظاهری ماشین)،
\fIDeployment\fR
(محیط استقرار سیستم) و
\fILocation\fR
(موقعیت فیزیکی سیستم) را تنظیم می‌کنند\&.
.PP
متد
\fBSetTags()\fR
برچسب‌های ماشین ارائه شده توسط ویژگی
\fITags\fR
را تنظیم می‌کند\&. این متد فهرستی از رشته‌ها را دریافت می‌کند که هر کدام باید یک برچسب معتبر ماشین باشند (۱ تا ۲۵۵ کاراکتر الفبایی‌عددی اسکی،
"\-"
و
"\&.")\&. ارسال یک فهرست خالی فیلد
\fITAGS=\fR
را از
/etc/machine\-info
حذف می‌کند\&.
.PP
ویژگی‌های
\fIPrettyHostname\fR،
\fIIconName\fR،
\fIChassis\fR،
\fIDeployment\fR،
\fILocation\fR
و
\fITags\fR
در
/etc/machine\-info
ذخیره می‌شوند\&. برای آگاهی از مفاهیم این تنظیمات به
\fBmachine-info\fR(5)
مراجعه کنید\&.
.PP
متد
\fBGetProductUUID()\fR
شناسه یکتای سراسری محصول («product UUID») را که توسط هسته بر اساس اطلاعات DMI در
/sys/class/dmi/id/product_uuid
ارائه شده است برمی‌گرداند\&. خواندن مستقیم این فایل نیازمند دسترسی ریشه (root) است و این متد امکان دسترسی کلاینت‌های بدون دسترسی ویژه را از طریق چارچوب polkit فراهم می‌کند\&.
.PP
متد
\fBGetHardwareSerial()\fR
«شماره سریال سخت‌افزار» (hardware serial) را که توسط هسته بر اساس اطلاعات DMI ارائه شده است برمی‌گرداند\&. خواندن مستقیم فایل نیازمند دسترسی ریشه (root) است و این متد دسترسی کلاینت‌های فاقد امتیاز ویژه را از طریق چارچوب polkit میسر می‌سازد\&.
.PP
متد
\fBDescribe()\fR
نمایش JSON تمامی ویژگی‌ها را به صورت یکجا برمی‌گرداند\&.
.PP
متد
\fBGetMachineInfo()\fR
مقدار فیلد داده‌شده را از
/etc/machine\-info
برمی‌گرداند\&. برای فیلدهای شناخته‌شده، این متد مقادیر را از همان حافظه موقت (cache) داخلی مورد استفاده توسط گیرنده‌های ویژگی مربوطه D\-Bus می‌خواند، اما تنها مقادیر خام
/etc/machine\-info
را برمی‌گرداند (یعنی بدون منطق جایگزین در سطح ویژگی مانند تشخیص مبتنی بر DMI/شاسی)\&. فیلدهای سفارشی (غیراستاندارد) مستقیماً از فایل خوانده می‌شوند\&. اگر نام فیلد خالی یا نامعتبر باشد، یا در فایل تنظیم نشده باشد، یک خطا برگردانده می‌شود\&.
.SS "امنیت (Security)"
.PP
پارامترهای بولی
\fIinteractive\fR
می‌توانند برای کنترل این موضوع استفاده شوند که آیا polkit در صورت نیاز باید اعتبارنامه‌های احراز هویت را به صورت تعاملی از کاربر درخواست کند یا خیر\&.
.PP
عملیات (action) مربوط به polkit برای
\fBSetHostname()\fR
برابر با
org\&.freedesktop\&.hostname1\&.set\-hostname
است\&. برای
\fBSetStaticHostname()\fR
و
\fBSetPrettyHostname()\fR
برابر با
org\&.freedesktop\&.hostname1\&.set\-static\-hostname
است\&. برای
\fBSetIconName()\fR،
\fBSetChassis()\fR،
\fBSetDeployment()\fR،
\fBSetLocation()\fR
و
\fBSetTags()\fR
برابر با
org\&.freedesktop\&.hostname1\&.set\-machine\-info
است\&.
.SH "توصیه‌ها (RECOMMENDATIONS)"
.PP
در اینجا سه مثال آورده شده است که نحوه استفاده از نام میزبان خوانا و نام آیکون را نشان می‌دهند:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
هنگام ثبت سرویس‌های DNS\-SD: از نام میزبان خوانا در نام سرویس استفاده کنید و در صورت وجود نام آیکون، آن را در داده‌های TXT ارسال نمایید\&. در این صورت کلاینت‌های مرورگر می‌توانند آیکون سرور را روی هر سرویس نمایش دهند\&. این ویژگی به ویژه برای برنامه‌های WebDAV یا اشتراک‌گذاری چندرسانه‌ای UPnP بسیار مفید است\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
تنظیم نام بلوتوث روی نام میزبان خوانا\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
هنگامی که مرورگر فایل شما دارای آیکون «Computer» است، در صورت تنظیم بودن نام میزبان خوانا، نام آن را با نام میزبان خوانا و آیکون آن را با نام آیکون جایگزین کنید\&.
.RE
.PP
برای مدیریت صحیح جستجوی نام با تغییر نام‌های میزبان محلی بدون نیاز به ویرایش
/etc/hosts،
توصیه می‌کنیم از
systemd\-hostnamed
همراه با
\fBnss-myhostname\fR(8)
استفاده کنید\&.
.PP
در ادامه توصیه‌هایی برای تولید یک نام میزبان ایستا (اینترنتی) از روی یک نام خوانا آورده شده است:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
فقط یک برچسب (label) منفرد DNS تولید کنید، نه یک FQDN\&. این بدان معنی است که هیچ نقطه‌ای مجاز نیست؛ آن‌ها را حذف کنید یا با
"\-"
جایگزین نمایید\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
احتمالاً ایمن‌تر است که از نویسه‌های غیر ASCII استفاده نکنید، حتی اگر امروزه DNS به نوعی این اجازه را بدهد\&. در واقع، مجموعه نویسه‌های خود را به
"a\-zA\-Z0\-9"
و
"\-"
محدود کنید\&. سایر نویسه‌ها را حذف کنید یا سعی کنید آن‌ها را به شیوه‌ای هوشمندانه با نویسه‌های این مجموعه جایگزین کنید، مثلاً
"ä"
→
"ae"، و از
"\-"
به عنوان جایگزین تمام علائم نگارشی و فاصله‌ها استفاده نمایید\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
سعی کنید از ایجاد
"\-"
پشت سر هم و همچنین قرار دادن
"\-"
به عنوان نویسه اول یا آخر خودداری کنید\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
طول نام میزبان را به ۶۳ نویسه محدود کنید که طول مجاز یک برچسب DNS است\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اگر پس از حذف نویسه‌های خاص نتیجه یک رشته خالی شد، می‌توانید آن را به همان شکل به
systemd\-hostnamed
ارسال کنید که در این صورت به طور خودکار از یک جایگزین مناسب استفاده خواهد کرد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
نویسه‌های بزرگ باید با معادل‌های کوچک خود جایگزین شوند\&.
.RE
.PP
توجه داشته باشید اگرچه
systemd\-hostnamed
برخی بررسی‌ها را روی نام میزبان ارسال‌شده اعمال می‌کند، اما این بررسی‌ها بسیار سهل‌گیرانه‌تر از توصیه‌های فوق هستند\&. به عنوان مثال،
systemd\-hostnamed
نویسه
"_"
را نیز در نام میزبان می‌پذیرد، اما برای جلوگیری از تداخل با انواع سرویس‌های DNS\-SD توصیه می‌کنیم از آن استفاده نکنید\&. همچنین
systemd\-hostnamed
نام‌های میزبان طولانی‌تر را نیز مجاز می‌داند، اما با توجه به محدودیت‌های برچسب DNS، توصیه می‌کنیم از آن بهره نگیرید\&.
.PP
در اینجا چند نمونه از این تبدیل‌ها آورده شده است:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
"Lennart\*(Aqs PC"
→
"lennarts\-pc"
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
"Müllers Computer"
→
"muellers\-computer"
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
"Voran!"
→
"voran"
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
"Es war einmal ein Männlein"
→
"es\-war\-einmal\-ein\-maennlein"
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
"Jawoll\&. Ist doch wahr!"
→
"jawoll\-ist\-doch\-wahr"
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
"レナート"
→
"localhost"
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
"\&.\&.\&.zack!!! zack!\&.\&.\&."
→
"zack\-zack"
.RE
.PP
البته، یک برچسب نام میزبان اینترنتی که از قبل معتبر است و آن را وارد کرده و از این تبدیل عبور می‌دهید، باید دست‌نخورده باقی بماند، تا کاربران در صورت تمایل کنترل مستقیمی بر آن داشته باشند \(em با نادیده گرفتن این واقعیت که نام میزبان خوانا یک نام زیبا است و صرفاً ویرایش آن به گونه‌ای که گویی نام عادی اینترنتی است\&.
.SH "مثال‌ها (EXAMPLES)"
.PP
\fBمثال\ \&۱.\ \&درون‌نگری org\&.freedesktop\&.hostname1 روی گذرگاه\fR
.sp
.if n \{\
.RS 4
.\}
.nf
$ gdbus introspect \-\-system \e
  \-\-dest org\&.freedesktop\&.hostname1 \e
  \-\-object\-path /org/freedesktop/hostname1
.fi
.if n \{\
.RE
.\}
.SH "سازگاری نسخه (VERSION COMPATIBILITY)"
.PP
این رابط‌های D\-Bus از
\m[blue]\fBدستورالعمل‌های معمول نسخه‌بندی رابط\fR\m[]\&\s-2\u[2]\d\s+2
پیروی می‌کنند\&.
.SH "تاریخچه (HISTORY)"
.SS "رابط D-Bus (The D-Bus API)"
.PP
\fIFirmwareVersion\fR
و
\fBGetHardwareSerial()\fR
در نسخه ۲۵۱ افزوده شدند\&.
.PP
\fIOperatingSystemSupportEnd\fR،
\fIFirmwareVendor\fR
و
\fIFirmwareDate\fR
در نسخه ۲۵۳ افزوده شدند\&.
.PP
\fIMachineID\fR،
\fIBootID\fR
و
\fIVSockCID\fR
در نسخه ۲۵۶ افزوده شدند\&.
.PP
\fIChassisAssetTag\fR،
\fIOperatingSystemImageID\fR،
\fIOperatingSystemImageVersion\fR،
\fIHardwareSKU\fR
و
\fIHardwareVersion\fR
در نسخه ۲۵۸ افزوده شدند\&.
.PP
\fIOperatingSystemFancyName\fR
در نسخه ۲۶۰ افزوده شد\&.
.PP
\fBGetMachineInfo()\fR،
\fITags\fR
و
\fBSetTags()\fR
در نسخه ۲۶۱ افزوده شدند\&.
.SH "همچنین ببینید (SEE ALSO)"
.PP
\fBsystemd\fR(1), \fBsystemd-hostnamed.service\fR(8), \fBhostnamectl\fR(1), \m[blue]\fBصفحه ویژگی اولیه دیوید زوتن در فدورا درباره xdg\-hostname\fR\m[]\&\s-2\u[3]\d\s+2
.SH "نکات (NOTES)"
.IP " 1." 4
polkit
.RS 4
\%https://www.freedesktop.org/software/polkit/docs/latest
.RE
.IP " 2." 4
دستورالعمل‌های معمول نسخه‌بندی رابط
.RS 4
\%https://0pointer.de/blog/projects/versioning-dbus.html
.RE
.IP " 3." 4
صفحه ویژگی درباره xdg-hostname
.RS 4
\%https://fedoraproject.org/wiki/Features/BetterHostname
.RE