Date: Thu, 29 Nov 2001 20:17:04 +0000 From: Ceri <setantae@submonkey.net> To: FreeBSD-gnats-submit@freebsd.org Subject: docs/32381: [PATCH] Handbook section on chrooting named is not correct Message-ID: <E169XcG-0002PM-00@rhadamanth.private.submonkey.net>
next in thread | raw e-mail | index | archive | help
>Number: 32381
>Category: docs
>Synopsis: [PATCH] Handbook section on chrooting named is not correct
>Confidential: no
>Severity: serious
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Thu Nov 29 12:20:00 PST 2001
>Closed-Date:
>Last-Modified:
>Originator: Ceri <setantae@submonkey.net>
>Release: FreeBSD 4.4-STABLE i386
>Organization:
>Environment:
System: FreeBSD rhadamanth.private.submonkey.net 4.4-STABLE FreeBSD 4.4-STABLE #0: Mon Nov 26 13:11:22 GMT 2001 setantae@rhadamanth.private.submonkey.net:/usr/obj/usr/src/sys/RHADAMANTH i386
Today's doc tree.
>Description:
The handbook's explanation of how to chroot named does not work.
>How-To-Repeat:
Read it.
>Fix:
Apply this patch.
As always, the markup may be dodgy, and comments are welcome.
Ceri
--- doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml.old Thu Nov 29 20:13:11 2001
+++ doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml Thu Nov 29 20:12:57 2001
@@ -131,10 +131,10 @@
will cover in the <link linkend="routing-default">next
section</link>) and the <hostid>localhost</hostid> route.</para>
- <indexterm><primary>loopback device</primary></indexterm>
- <para>The interface (<literal>Netif</literal> column) that it specifies
- to use for <literal>localhost</literal> is
- <devicename>lo0</devicename>, also known as the loopback device. This
+<indexterm><primary>loopback device</primary></indexterm>
+<para>The interface (<literal>Netif</literal> column) that it specifies
+to use for <literal>localhost</literal> is
+<devicename>lo0</devicename>, also known as the loopback device. This
says to keep all traffic for this destination internal, rather than
sending it out over the LAN, since it will only end up back where it
started.</para>
@@ -4150,8 +4150,9 @@
<sect2info>
<authorgroup>
<author>
- <firstname>Mike</firstname>
- <surname>Makonnen</surname>
+ <firstname>Ceri</firstname>
+ <surname>Davies</surname>
+ <address><email>setantae@submonkey.net</email></address>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
@@ -4166,105 +4167,199 @@
<indexterm>
<primary><command>chroot</command></primary>
</indexterm>
- <para>For added security you may want to run &man.named.8; in a
- sandbox. This will reduce the potential damage should it be
- compromised. If you include a sandbox directory in its command
- line, named will &man.chroot.8;
- into that directory immediately upon finishing processing its
- command line. It is also a good idea to have named run as a
- non-privileged user in the sandbox. The default FreeBSD install
- contains a user bind with group bind. If we wanted the sandbox in
- the <filename>/etc/namedb/sandbox</filename> directory the command
- line for named would look like this:
- </para>
- <screen> &prompt.root; <userinput>/usr/sbin/named -u bind -g bind -t /etc/namedb/sandbox <path_to_named.conf> </userinput></screen>
-
- <para>The following steps should be taken in order to
- successfully run named in a sandbox. Throughout the following
- discussion we will assume the path to your sandbox is
- <filename>/etc/namedb/sandbox</filename>
- </para>
+ <para>For added security you may want to run &man.named.8; as an
+ unprivileged user, and configure it to &man.chroot.8; into a
+ sandbox directory. This makes everything outside of the sandbox
+ inaccessible to the <application>named</application> daemon. Should
+ <application>named</application> be compromised, this will help to
+ reduce the damage that can be caused. By default, FreeBSD has a user
+ and a group called <quote>bind</quote>, intended for this use.</para>
+
+ <para><note>Various people would recommend that instead of configuring
+ <application>named</application> to <command>chroot</command>, you
+ should run <application>named</application> inside a &man.jail.8;. This
+ section does not attempt to cover this situation.</note></para>
+
+ <para>Since <application>named</application> will not be able to
+ access anything outside of the sandbox (such as shared libraries,
+ log sockets, etc.), there are a number of steps that need to be
+ followed in order to allow <application>named</application> to
+ function correctly. In the following checklist, it is assumed
+ that the path to the sandbox is <filename>/etc/namedb</filename>
+ and that you have made no prior modifications to the contents of
+ this directory. Perform the following steps as root.</para>
<itemizedlist>
- <listitem>
- <para>Create the sandbox directory:
- <filename>/etc/namedb/sandbox</filename></para>
- </listitem>
- <listitem>
- <para>Create other necessary directories off of the sandbox
- directory: <filename>etc</filename> and
- <filename>var/run</filename></para>
- </listitem>
- <listitem>
- <para>copy <filename>/etc/localtime</filename> to
- <filename>sandbox/etc</filename>
- </para>
- </listitem>
- <listitem>
- <para>make bind:bind the owner of all files and directories in
- the sandbox:
- <screen>&prompt.root; <userinput>chown -R bind:bind /etc/namedb/sandbox</userinput> </screen>
- <screen>&prompt.root; <userinput>chmod -R 750 /etc/namedb/sandbox</userinput> </screen>
- </para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para>Create all directories that <application>named</application>
+ expects to see:</para>
- <para>There are some issues you need to be aware of when running
- named in a sandbox.</para>
+ <screen>&prompt.root; <userinput>cd /etc/namedb</userinput>
+&prompt.root; <userinput>mkdir -p bin dev etc var/tmp var/run master slave</userinput>
+&prompt.root; <userinput>chown bind:bind slave var/*</userinput></screen><co id="chown-slave"></co>
- <itemizedlist>
- <listitem>
- <para>Your &man.named.conf.5; file and all your zone files must
- be in the sandbox
- </para>
- </listitem>
- <listitem>
- <para><filename>sandbox/etc/localtime</filename> is needed
- in order to have the correct time for your time zone in
- log messages.</para>
- </listitem>
- <listitem>
- <para> &man.named.8; will write its process id to a file in
- <filename>sandbox/var/run</filename></para>
- </listitem>
- <listitem>
- <para>The Unix socket used for communication by the &man.ndc.8;
- utility will be created in
- <filename>sandbox/var/run</filename></para>
- </listitem>
- <listitem>
- <para>When using the &man.ndc.8; utility you need to specify the
- location of the Unix socket created in the sandbox, by
- &man.named.8;, by using the -c switch:
- <command>&prompt.root; ndc -c /etc/namedb/sandbox/var/run/ndc</command>
- </para>
- </listitem>
- <listitem>
- <para>If you enable logging to file, the log files must be
- in the sandbox</para>
- </listitem>
- </itemizedlist>
+ <calloutlist>
+ <callout arearefs="chown-slave">
+ <para><application>named</application> only needs write access to
+ these directories, so that is all we give it.</para>
+ </callout>
+ </calloutlist>
+ </listitem>
+ <listitem>
+ <para>Rearrange and create basic zone and configuration files:</para>
+ <screen>&prompt.root; <userinput>cp /etc/localtime etc</userinput><co id="localtime"></co>
+&prompt.root; <userinput>mv named.conf etc && ln -sf etc/named.conf</userinput>
+&prompt.root; <userinput>mv named.root master</userinput>
+<!-- I don't like this next bit -->
+&prompt.root; <userinput>sh make-localhost && mv localhost.rev master</userinput>
+&prompt.root; <userinput>cat > named.localhost
+$ORIGIN localhost.
+$TTL 6h
+@ IN SOA localhost. postmaster.localhost. (
+ 1 ; serial
+ 3600 ; refresh
+ 1800 ; retry
+ 604800 ; expiration
+ 3600 ) ; minimum
+ IN NS localhost.
+ IN A 127.0.0.1
+^D</userinput></screen>
- <para>&man.named.8; can be started in a sandbox properly, if the
- following is in <filename>/etc/rc.conf</filename>:
- </para>
- <programlisting>named_flags="-u bind -g bind -t /etc/namedb/sandbox <path_to_named.conf>"</programlisting>
- </sect2>
+ <calloutlist>
+ <callout arearefs="localtime">
+ <para>This allows <application>named</application> to log the
+ correct time to &man.syslogd.8;</para>
+ </callout>
+ </calloutlist>
+ </listitem>
+ <listitem>
+ <para>Build a statically linked copy of
+ <application>named-xfer</application>, and copy it into the sandbox:</para>
- <sect2>
- <title>How to Use the Name Server</title>
+ <screen>&prompt.root; <userinput>cd /usr/src/lib/libisc && make clean all</userinput>
+&prompt.root; <userinput>cd /usr/src/lib/libbind && make clean all</userinput>
+&prompt.root; <userinput>cd /usr/src/libexec/named-xfer && make NOSHARED=yes all</userinput>
+&prompt.root; <userinput>cp named-xfer /etc/namedb/bin && chmod 555 /etc/namedb/bin/named-xfer</userinput></screen>
+ </listitem>
+ <listitem>
+ <para>Make a <devicename>dev/null</devicename> that
+ <application>named</application> can see and write to:</para>
- <para>If setup properly, the name server should be accessible through
- the network and locally. <filename>/etc/resolv.conf</filename> must
- contain a name server entry with the local IP address so it will query the
- local name server first.
- </para>
+ <screen>&prompt.root; <userinput>cd /etc/namedb/dev && mknod null c 2 2</userinput>
+&prompt.root; <userinput>chmod 666 null</userinput></screen>
+ </listitem>
+ <listitem>
+ <para>Symlink <filename> /var/run/ndc</filename> to
+ <filename>/etc/namedb/var/run/ndc</filename>:</para>
+
+ <screen>&prompt.root; <userinput>ln -sf /etc/namedb/var/run/ndc /var/run/ndc</userinput></screen>
+
+ <para><note>This simply avoids having to specify the <option>-c</option>
+ option to &man.ndc.8; every time you run it. If this is something
+ that you find useful, you may wish to add this entry to root's
+ crontab, making use of the <option>@reboot</option> option. See
+ &man.crontab.5; for more information regarding this.</note></para>
+ </listitem>
+ <listitem>
+ <para>Configure &man.syslogd.8; to create an extra <devicename>log</devicename>
+ socket that <application>named</application> can write to. To do
+ this, add <literal>-l /etc/namedb/dev/log</literal> to the
+ <variable>syslogd_flags</variable> variable in
+ <filename>/etc/rc.conf</filename>.</para>
+ </listitem>
+ <listitem>
+ <para>Arrange to have <application>named</application> start and
+ <command>chroot</command> itself to the sandbox by adding the following
+ to <filename>/etc/rc.conf</filename>:</para>
+ <programlisting>named_enable="YES"
+named_flags="-u bind -g bind -t /etc/namedb /etc/named.conf"</programlisting>
+
+ <para><note>Note that the configuration file
+ <replaceable>/etc/named.conf</replaceable> is denoted by a full
+ pathname <emphasis>relative to the sandbox</emphasis>, i.e. in
+ the line above, the file referred to is actually
+ <filename>/etc/namedb/etc/named.conf</filename>/</note></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The next step is to edit <filename>/etc/namedb/etc/named.conf</filename>
+ so that <application>named</application> knows which zones to load and
+ where to find them on the disk. There follows a commented example
+ (anything not specifically commented here is no different from the
+ setup for a DNS server not running in a sandbox):</para>
+
+ <programlisting>options {
+ directory "/";<co id="directory"></co>
+ named-xfer "/bin/named-xfer";<co id="named-xfer"></co>
+ version ""; // Don't reveal BIND version
+ query-source address * port 53;
+};
+// ndc control socket
+controls {
+ unix "/var/run/ndc" perm 0600 owner 0 group 0;
+};
+// Zones follow:
+zone "localhost" IN {
+ type master;
+ file "master/named.localhost";<co id="master"></co>
+ allow-transfer { localhost; };
+ notify no;
+};
+zone "0.0.127.in-addr.arpa" IN {
+ type master;
+ file "master/named.loopback";
+ allow-transfer { localhost; };
+ notify no;
+};
+zone "." IN {
+ type hint;
+ file "master/named.root";
+};
+zone "private.example.net" in {
+ type master;
+ file "master/private.example.net.db";
+ allow-transfer { 192.168.10.0/24; };
+};
+zone "10.168.192.in-addr.arpa" in {
+ type slave;
+ masters { 192.168.10.2; };
+ file "slave/192.168.10.db";<co id="slave"></co>
+};</programlisting>
+
+ <calloutlist>
+ <callout arearefs="directory"><para>The <literal>directory</literal>
+ statement is specified as <filename>/</filename>, since all files
+ that <application>named</application> needs are within this directory
+ (recall that this is equivalent to a <quote>normal</quote> user's
+ <filename>/etc/namedb</filename>.</para>
+ </callout>
+ <callout arearefs="named-xfer"><para>Specifies the full path to the
+ <command>named-xfer</command> binary (from <application>named</application>'s
+ frame of reference). This is necessary since <application>named</application>
+ is compiled to look for <command>named-xfer</command> in
+ <filename>/usr/libexec</filename> by default.</para>
+ </callout>
+ <callout arearefs="master"><para>Specifies the filename (relative
+ to the <literal>directory</literal> statement above) where
+ <application>named</application> can find the zonefile for this
+ zone.</para>
+ </callout>
+ <callout arearefs="slave"><para>Specifies the filename (relative
+ to the <literal>directory</literal> statement above) where
+ <application>named</application> should write a copy of the
+ zonefile for this zone after successfully transferring it from
+ the master server. This is why we needed to change the ownership
+ of the directory <filename>slave</filename> to <quote>bind</quote>
+ in the setup stages above.</para>
+ </callout>
+ </calloutlist>
+
+ <para>After completing the steps above, either reboot your server or
+ restart &man.syslogd.8 and start &man.named.8, making sure to use the
+ new options specified in <variable>syslogd_flags</variable> and
+ <variable>named_flags</variable>. You should now be running a sandboxed
+ copy of <application>named</application>!</para>
- <para>
- To access it over the network, the machine must have the
- name server's IP address set properly in its own name server
- configuration options.
- </para>
</sect2>
<sect2>
>Release-Note:
>Audit-Trail:
>Unformatted:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?E169XcG-0002PM-00>