.\" Copyright (c) 2009-2025 Roy Marples
.\" All rights reserved
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd May 15, 2025
.Dt RESOLVCONF.CONF 5
.Os
.SH "نام (NAME)"
resolvconf.conf \- پرونده پیکربندی resolvconf
.Sh "توضیحات (DESCRIPTION)"
.Nm
پرونده پیکربندی برای
.Xr resolvconf 8
است.
پرونده
.Nm
یک اسکریپت شل است که توسط
.Xr resolvconf 8
منبع‌دهی (source) می‌شود، به این معنی که
.Nm
باید حاوی دستورات معتبر شل باشد.
در زیر متغیرهای استاندارد
.Nm
که می‌توانند مقداردهی شوند فهرست شده‌اند.
اگر مقادیر حاوی فاصله، نویسه‌های عام (wildcards) یا سایر نویسه‌های ویژه شل هستند،
اطمینان حاصل کنید که به درستی درون نقل‌قول قرار گرفته و گریز داده شده‌اند (escaped).
برای مشاهده مثالی از نقل‌قول به متغیر
.Sy replace
مراجعه کنید.
.Pp
پس از به‌روزرسانی این پرونده، ممکن است بخواهید
.Nm resolvconf -u
را برای اعمال پیکربندی جدید اجرا کنید.
.Pp
هنگامی که به یک فهرست تولیدشده به صورت پویا مقداری افزوده (append) یا پیش‌افزوده (prepend) می‌شود، کل فهرست به گونه‌ای یکتا می‌شود که اولویت با سمت‌چپ‌ترین ورودی است.
.Sh "گزینه‌های RESOLVCONF (RESOLVCONF OPTIONS)"
.Bl -tag -width indent
.It Sy resolvconf
برای غیرفعال کردن اجرای هرگونه مشترک توسط
.Nm resolvconf
روی NO تنظیم کنید.
پیش‌فرض YES است.
.It Sy allow_keys
در صورت تنظیم، تنها این کلیدها پردازش خواهند شد.
.It Sy deny_keys
در صورت تنظیم، این کلیدها پردازش نخواهند شد.
.It Sy exclude
فهرستی از جفت‌های کلید/مقدار جدا شده با فاصله برای تطابق است.
اگر تمام جفت‌های کلید/مقدار در یک عنصر درون پرونده یافت شوند،
کل پرونده از پردازش حذف خواهد شد.
نحو به این صورت است:
.Va $keyword Ns / Ns Va $match Ns Op / Ns Va $keyword Ns / Ns Va $match
.Pp
برای نمونه با فرض این پیکربندی:
.Bd -literal -compact -offset indent
exclude="search/foo*/nameserver/1.2.3.4 search/bar.org"
.Ed
.Pp
هر resolv.conf که هم دارای گزینه search شروع‌شونده با foo به همراه nameserver برابر با 1.2.3.4 باشد
یا گزینه search برابر با bar.org داشته باشد، از پردازش کنار گذاشته می‌شود.
.It Sy key_order
این کلیدها همیشه در ابتدا پردازش خواهند شد.
در صورت عدم تنظیم، به طور پیش‌فرض مقادیر زیر است:
.Bd -literal -compact -offset indent
lo lo[0-9]*
.Ed
.It Sy dynamic_order
این کلیدها در مرحله بعد پردازش خواهند شد، مگر اینکه دارای یک متریک (metric) باشند.
در صورت عدم تنظیم، به طور پیش‌فرض مقادیر زیر است:
.Bd -literal -compact -offset indent
tap[0-9]* tun[0-9]* vpn vpn[0-9]* wg[0-9]* ppp[0-9]* ippp[0-9]*
.Ed
.It Sy inclusive_keys
هرگونه علامت‌گذاری انحصاری (exclusive) برای این کلیدها نادیده گرفته می‌شود.
این گزینه زمانی کاربرد دارد که ابزارهای یکپارچه‌سازی شخص ثالث گزینه
.Nm resolvconf -x
را تحمیل می‌کنند و شما می‌خواهید آن را به آسانی غیرفعال کنید.
.It Sy local_nameservers
در صورت عدم تنظیم، به طور پیش‌فرض مقادیر زیر است:
.Bd -literal -compact -offset indent
127.* 0.0.0.0 255.255.255.255 ::1
.Ed
.It Sy search_domains
دامنه‌های جستجو را به ابتدای فهرست پویای تولیدشده اضافه می‌کند (prepend).
.It Sy search_domains_append
دامنه‌های جستجو را به انتهای فهرست پویای تولیدشده اضافه می‌کند (append).
.It Sy domain_blacklist
فهرستی از دامنه‌ها که باید از محاسبات حذف شوند.
برای حذف یک دامنه، می‌توانید از foo.* استفاده کنید.
برای حذف یک زیردامنه، می‌توانید از *.bar استفاده کنید.
.It Sy name_servers
سرورهای نام (name servers) را به ابتدای فهرست پویای تولیدشده اضافه می‌کند (prepend).
اگر از سرور نام محلی غیر از libc استفاده می‌کنید، باید این متغیر را روی 127.0.0.1 تنظیم کنید.
.It Sy name_servers_append
سرورهای نام را به انتهای فهرست پویای تولیدشده اضافه می‌کند (append).
.It Sy name_server_blacklist
فهرستی از سرورهای نام که باید از محاسبات حذف شوند.
مقدار پیش‌فرض 0.0.0.0 است، زیرا برخی روترهای معیوب آن را از طریق DHCP ارسال می‌کنند.
برای حذف یک بلوک، می‌توانید از 192.168.* استفاده کنید.
.It Sy private_keys
از سرورهای نام مربوط به این کلیدها فقط برای دامنه‌های فهرست‌شده در resolv.conf خودشان پرس‌وجو می‌شود.
برای دامنه‌های VPN مفید است.
تنظیم
.Sy private_keys Ns ="*"
هدایت ناحیه ریشه (root zone forwarding) را متوقف می‌کند و به تحلیل‌گر محلی اجازه می‌دهد مستقیماً و به صورت بازگشتی (recursively) از سرورهای ریشه پرس‌وجو کند.
نیازمند یک سرور نام محلی به جز libc است.
این متغیر معادل گزینه
.Nm resolvconf -p
است.
.It Sy nosearch_keys
دامنه‌ها/جستجوی این کلیدها به فهرست جستجوی سراسری در
.Pa /etc/resolv.conf
اضافه نخواهد شد.
.It Sy public_keys
این کلیدها را مجبور به عمومی بودن می‌کند و علامت‌گذاری‌های private و nosearch را نادیده می‌گیرد.
این گزینه زمانی مفید است که یکپارچه‌سازی‌های شخص ثالث گزینه
.Nm resolvconf -p
را تحمیل می‌کنند و شما می‌خواهید آن را به راحتی غیرفعال کنید.
.It Sy replace
فهرستی از کلمات کلیدی جایگزینی جدا شده با فاصله است.
نحو به این صورت است:
.Va $keyword Ns / Ns Va $match Ns / Ns Va $replacement
.Pp
برای نمونه، با فرض این resolv.conf:
.Bd -literal -compact -offset indent
domain foo.org
search foo.org dead.beef
nameserver 1.2.3.4
nameserver 2.3.4.5
.Ed
.Pp
و این پیکربندی:
.Bd -literal -compact -offset indent
replace="search/foo*/bar.com"
replace="$replace nameserver/1.2.3.4/5.6.7.8"
replace="$replace nameserver/2.3.4.5/"
.Ed
.Pp
در عوض چنین resolv.conf دریافت خواهید کرد:
.Bd -literal -compact -offset indent
domain foo.org
search bar.com
nameserver 5.6.7.8
.Ed
.Pp
.It Sy replace_sub
همانند
.Sy replace
عمل می‌کند با این تفاوت که به جای کل خط، روی هر مقدار جدا شده با فاصله اعمال می‌شود،
بنابراین برای جایگزینی یک تک‌دامنه در دستورالعمل search مفید است.
با استفاده از همان resolv.conf نمونه و تغییر
.Sy replace
به
.Sy replace_sub ،
در عوض چنین resolv.conf دریافت خواهید کرد:
.Bd -literal -compact -offset indent
domain foo.org
search bar.com dead.beef
nameserver 5.6.7.8
.Ed
.Pp
.It Sy state_dir
پوشه وضعیت پیش‌فرض
.Pa /run/resolvconf
را بازنویسی می‌کند.
پس از این‌که
.Nm resolvconf
مورد استفاده قرار گرفت، نباید تغییر داده شود مگر اینکه پوشه قدیمی به پوشه جدید کپی شود.
.El
.Sh "گزینه‌های LIBC (LIBC OPTIONS)"
متغیرهای زیر مستقیماً بر
.Xr resolv.conf 5
اثر می‌گذارند:
.Bl -tag -width indent
.It Sy resolv_conf
در صورت عدم تنظیم، به طور پیش‌فرض
.Pa /etc/resolv.conf
است.
تنظیم آن روی
.Pa /dev/null
از تغییر آن توسط
.Xr resolvconf 8
جلوگیری می‌کند.
.It Sy resolv_conf_options
فهرستی از گزینه‌های تحلیل‌گر libc، مطابق با آنچه در
.Xr resolv.conf 5
مشخص شده است.
.It Sy resolv_conf_passthrough
هنگامی که روی YES تنظیم شود، آخرین resolv.conf بدون هیچ‌گونه تغییری در
.Sy resolv_conf
نوشته می‌شود.
هنگامی که روی /dev/null یا NULL تنظیم شود، مقدار پیش‌فرض
.Sy resolv_conf_local_only
برابر با NO می‌شود،
.Sy local_nameservers
تنظیم‌نشده باقی می‌ماند مگر بازنویسی شود و تنها اطلاعات تنظیم‌شده در
.Nm
در
.Sy resolv_conf
نوشته می‌شود.
.It Sy resolv_conf_restore
هنگامی که روی YES تنظیم شود و قرار باشد یک
.Pa resolv.conf
خالی نوشته شود، در صورتی که
.Pa resolv.conf.bak
وجود داشته باشد، به جای آن بازیابی می‌شود.
در صورت عدم تنظیم، به طور پیش‌فرض YES است.
.It Sy resolv_conf_sortlist
یک sortlist تحلیل‌گر libc، مطابق با آنچه در
.Xr resolv.conf 5
مشخص شده است.
.It Sy resolv_conf_local_only
اگر یک سرور نام محلی پیکربندی شده باشد، رفتار پیش‌فرض این است که تنها همان سرور نام مشخص شود و تمام ورودی‌های دیگر نادیده گرفته شوند، چرا که برای سرور نام محلی پیکربندی خواهند شد.
برای فهرست کردن سرورهای نام غیرمحلی نیز این متغیر را روی NO تنظیم کنید.
این کار در صورت از کار افتادن سرور نام محلی به بهای تکرار پرس‌وجوهای سرور، یک DNS فعال در اختیار شما قرار می‌دهد.
.It Sy append_nameservers
سرورهای نام را به انتهای فهرست تولیدشده به صورت پویا اضافه می‌کند (append).
.It Sy prepend_nameservers
سرورهای نام را به ابتدای فهرست تولیدشده به صورت پویا اضافه می‌کند (prepend).
.It Sy append_search
دامنه‌های جستجو را به انتهای فهرست تولیدشده به صورت پویا اضافه می‌کند (append).
.It Sy prepend_search
دامنه‌های جستجو را به ابتدای فهرست تولیدشده به صورت پویا اضافه می‌کند (prepend).
.It Sy resolv_conf_mv
پیش‌فرض NO است.
مشخص می‌کند که آیا
.Pa /etc/resolv.conf
با نوشتن در یک پرونده موقت و سپس انتقال آن به‌روزرسانی شود، یا اینکه مستقیماً در آن نوشته شود.
.El
.Sh "گزینه‌های مشترکین (SUBSCRIBER OPTIONS)"
openresolv به همراه مشترکینی برای سرورهای نام زیر عرضه می‌شود:
.Xr dnsmasq 8 ،
.Xr named 8 ،
.Xr pdnsd 8 ،
.Xr pdns_recursor 1
و
.Xr unbound 8 .
هر مشترک می‌تواند پرونده‌های پیکربندی ایجاد کند که باید در پرونده پیکربندی اصلی آن مشترک گنجانده شوند (include).
.Pp
برای غیرفعال کردن یک مشترک، کافی است نام آن را روی NO تنظیم کنید.
اگر نام مشترک دارای خط پیوند (dash) است، آن را با زیرخط (underscore) جایگزین کنید.
برای نمونه، جهت غیرفعال کردن مشترک libc باید تنظیم کنید:
.Bd -literal -compact -offset indent
libc=NO
.Ed
.Bl -tag -width indent
.It Sy dnsmasq_conf
این پرونده به dnsmasq اعلام می‌کند که برای دامنه‌های خاص از کدام سرورهای نام استفاده کند.
.It Sy dnsmasq_resolv
این پرونده به dnsmasq اعلام می‌کند که برای جستجوهای سراسری از کدام سرورهای نام استفاده کند.
.Pp
نمونه resolvconf.conf برای dnsmasq:
.Bd -literal -compact -offset indent
name_servers=127.0.0.1
dnsmasq_conf=/etc/dnsmasq-conf.conf
dnsmasq_resolv=/etc/dnsmasq-resolv.conf
.Ed
.Pp
نمونه dnsmasq.conf:
.Bd -literal -compact -offset indent
listen-address=127.0.0.1
# If dnsmasq is compiled for DBus then we can take
# advantage of not having to restart dnsmasq.
enable-dbus
conf-file=/etc/dnsmasq-conf.conf
resolv-file=/etc/dnsmasq-resolv.conf
.Ed
.It Sy named_options
این پرونده را در بلوک options برنامه named بگنجانید (include).
این پرونده به named اعلام می‌کند که برای جستجوهای سراسری از کدام سرورهای نام استفاده کند.
.It Sy named_zones
این پرونده را در دامنه سراسری (global scope) برنامه named، پس از بلوک options بگنجانید.
این پرونده به named اعلام می‌کند که برای دامنه‌های خاص از کدام سرورهای نام استفاده کند.
.Pp
نمونه resolvconf.conf برای named:
.Bd -literal -compact -offset indent
name_servers=127.0.0.1
named_options=/etc/named-options.conf
named_zones=/etc/named-zones.conf
.Ed
.Pp
نمونه named.conf:
.Bd -literal -compact -offset indent
options {
	listen-on { 127.0.0.1; };
	include "/etc/named-options.conf";
};

include "/etc/named-zones.conf";
.Ed
.It Sy pdnsd_conf
این پرونده پیکربندی اصلی pdnsd است که ما برای اضافه کردن دامنه‌های هدایتی (forward domains) خود آن را اصلاح می‌کنیم.
اگر این متغیر تنظیم نشود، به راه‌اندازی پرونده پیکربندی pdnsd تکیه می‌کنیم تا
.Pa pdnsd_resolv
را همان‌گونه که در زیر شرح داده شده بخواند.
.It Sy pdnsd_resolv
این پرونده سرورهای نام سراسری را به pdnsd معرفی می‌کند.
اگر این متغیر تنظیم نشود، در
.Pa pdnsd_conf
نوشته می‌شود.
.Pp
نمونه resolvconf.conf برای pdnsd:
.Bd -literal -compact -offset indent
name_servers=127.0.0.1
pdnsd_conf=/etc/pdnsd.conf
# pdnsd_resolv=/etc/pdnsd-resolv.conf
.Ed
.Pp
نمونه pdnsd.conf:
.Bd -literal -compact -offset indent
global {
	server_ip = 127.0.0.1;
	status_ctl = on;
}
server {
	# A server definition is required, even if empty.
	label="empty";
	proxy_only=on;
	# file="/etc/pdnsd-resolv.conf";
}
.Ed
.It Sy pdns_zones
این پرونده سرورهای نام خاص و سراسری را به pdns_recursor معرفی می‌کند.
.Pp
نمونه resolvconf.conf برای pdns_recursor:
.Bd -literal -compact -offset indent
name_servers=127.0.0.1
pdns_zones=/etc/pdns/recursor-zones.conf
.Ed
.Pp
نمونه recursor.conf:
.Bd -literal -compact -offset indent
allow-from=127.0.0.0/8, ::1/128
forward-zones-file=/etc/pdns/recursor-zones.conf
.Ed
.It Sy resolvectl
هنگامی که روی YES تنظیم شود، از
.Xr resolvectl 1
برای نوشتن ورودی‌های هر رابط از
.Xr resolvconf 8
در
.Xr systemd-resolved 8
استفاده خواهد شد.
برای هر ورودی که نتوان آن را با یک رابط تطبیق داد، یک هشدار صادر می‌شود.
.Pp
این مشترک تنها باید زمانی استفاده شود که systemd-resolved شما از DNS delegates پشتیبانی نمی‌کند و به ورودی‌های خصوصی (private) یا غیرقابل‌جستجوی
.Xr resolvconf 8
نیاز دارید، یا واقعاً متعهد به دیدن تنظیمات DNS به ازای هر رابط از طریق
.Xr resolvectl 1
هستید.
مشترک systemd-resolved که در زیر مستند شده است، گزینه بهتری محسوب می‌شود.
.Pp
نمونه resolvconf.conf برای resolvectl:
.Bd -literal -compact -offset indent
# Keep /etc/resolv.conf as systemd-resolved wants it
libc=NO
resolvectl=YES
.Ed
.It Sy systemd_resolved
هنگامی که روی YES تنظیم شود، DNS سراسری در پرونده پیکربندی
.Sy systemd_resolved_conf
نوشته می‌شود و DNS delegates در پوشه
.Sy systemd_delegate_dir
نوشته خواهد شد.
.It Sy systemd_resolved_conf
پیش‌فرض
.Pa /run/systemd/resolved.conf.d/60-resolvconf.conf
است.
.It Sy systemd_delegate_dir
پیش‌فرض
.Pa /run/systemd/dns-delegate.d
است.
.Pp
نمونه resolvconf.conf برای systemd-resolved:
.Bd -literal -compact -offset indent
# Keep /etc/resolv.conf as systemd-resolved wants it
libc=NO
systemd_resolved=YES
.Ed
.It Sy unbound_conf
این پرونده سرورهای نام خاص و سراسری را به unbound معرفی می‌کند.
.It Sy unbound_insecure
هنگامی که روی YES تنظیم شود، unbound دامنه‌ها را به عنوان ناامن (insecure) علامت‌گذاری می‌کند و در نتیجه DNSSEC نادیده گرفته می‌شود.
.It Sy unbound_private
هنگامی که روی YES تنظیم شود، unbound دامنه‌ها را به عنوان خصوصی (private) علامت‌گذاری می‌کند و به آن و زیردامنه‌هایش اجازه می‌دهد حاوی آدرس‌های خصوصی باشند.
.It Sy unbound_forward_zone_options
گزینه‌هایی که به هر forward zone اضافه می‌شوند.
هر گزینه باید با یک خط جدید درج‌شده (newline) جدا شود.
.Pp
نمونه resolvconf.conf برای unbound:
.Bd -literal -compact -offset indent
name_servers=127.0.0.1
unbound_conf=/etc/unbound-resolvconf.conf
.Ed
.Pp
نمونه unbound.conf:
.Bd -literal -compact -offset indent
include: /etc/unbound-resolvconf.conf
.Ed
.El
.Sh "یکپارچه‌سازی مشترکین (SUBSCRIBER INTEGRATION)"
همه توزیع‌ها پرونده‌های مورد نیاز مشترکین را در مکان‌های یکسانی ذخیره نمی‌کنند.
برای نمونه، اسکریپت‌های سرویس named با نام‌های named، bind و rc.bind نام‌گذاری شده‌اند و ممکن است در دایرکتوری به نام /etc/rc.d، /etc/init.d یا موارد مشابه قرار داشته باشند.
هر مشترک تلاش می‌کند تا خود را به طور خودکار پیکربندی کند، اما همه توزیع‌ها در نظر گرفته نشده‌اند.
همچنین، کاربران ممکن است بخواهند از نسخه‌ای متفاوت از نسخه نصب‌شده به طور پیش‌فرض استفاده کنند، مانند bind8 و bind9.
برای سازگاری با این شرایط، مشترکین این پرونده‌ها را در متغیرهای قابل‌پیکربندی قرار داده‌اند که در ادامه مستند شده‌اند.
.Bl -tag -width indent
.It Sy dnsmasq_service
نام سرویس dnsmasq.
.It Sy dnsmasq_restart
دستور راه‌اندازی مجدد سرویس dnsmasq.
.It Sy dnsmasq_pid
محل پرونده pid سرویس dnsmasq.
.It Sy libc_service
نام سرویس libc.
.It Sy libc_restart
دستور راه‌اندازی مجدد سرویس libc.
.It Sy named_service
نام سرویس named.
.It Sy named_restart
دستور راه‌اندازی مجدد سرویس named.
.It Sy pdnsd_restart
دستور راه‌اندازی مجدد سرویس pdnsd.
.It Sy pdns_service
دستور راه‌اندازی مجدد سرویس pdns_recursor.
.It Sy pdns_restart
دستور راه‌اندازی مجدد سرویس pdns_recursor.
.It Sy unbound_service
نام سرویس unbound.
.It Sy unbound_restart
دستور راه‌اندازی مجدد سرویس unbound.
.It Sy unbound_pid
محل پرونده pid سرویس unbound.
.El
.Sh "همچنین ببینید (SEE ALSO)"
.Xr sh 1 ,
.Xr resolv.conf 5 ,
.Xr resolvconf 8
.Sh "نویسندگان (AUTHORS)"
.An Roy Marples Aq Mt roy@marples.name
.Sh "اشکالات (BUGS)"
هر توزیع ویژگی‌های منحصر‌به‌فرد خود را دارد و ترجیح می‌دهد موارد یکسان را به صورت متفاوت نام‌گذاری کند، به ویژه اسکریپت سرویس named.
.Pp
جابجایی بین مشترکین resolvectl و systemd-resolved در زمان اجرا پشتیبانی نمی‌شود.
پرونده‌های ارجاع‌شده توسط systemd_resolved_conf و systemd_delegate_dir باید به صورت دستی حذف شوند.
راه‌اندازی مجدد سیستم (reboot) توصیه می‌شود تا داده‌های کهنه پاک شوند.
اگرچه می‌توانید هر دوی آن‌ها را به طور همزمان اجرا کنید، اما استفاده از تنها یکی از آن‌ها روش پیشنهادی است.
.Pp
لطفاً اشکالات را به
.Lk https://roy.marples.name/projects/openresolv
گزارش دهید.