Attachment #115566 for bug #157337

View | Details | Raw Unified | Return to bug 157337
Collapse All | Expand All




  <chapterinfo>
    <authorgroup>
      <author>
	<firstname>Murray</firstname>
	<surname>Stokely</surname>
	<contrib>Reorganized by </contrib>
      </author>

      </listitem>

      <listitem>
	<para>Know how to install additional third-party
	  software (<xref linkend="ports">).</para>
      </listitem>

    </itemizedlist>

  <sect1 id="network-inetd">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Chern</firstname>
	  <surname>Lee</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>

	modify its behaviour.  The full list of options reads:</para>

      <para><command>inetd</command> <option>[-d] [-l] [-w] [-W] [-c maximum] [-C rate] [-a address | hostname]
	[-p filename] [-R rate] [-s maximum] [configuration file]</option></para>

      <para>Options can be passed to <application>inetd</application> using the
	<literal>inetd_flags</literal> option in

	      limits the number of children that can be started on
	      behalf on any single IP address at any moment. These
	      options are useful to prevent intentional or unintentional
	      excessive resource consumption and Denial of Service (DoS)
	      attacks to a machine.</para>

	    <para>In this field, either of <option>wait</option> or

  <sect1 id="network-nfs">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Tom</firstname>
	  <surname>Rhodes</surname>
	  <contrib>Reorganized and enhanced by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>
	  <firstname>Bill</firstname>
	  <surname>Swingle</surname>
	  <contrib>Written by </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>Network File System (NFS)</title>

      <title>How <acronym>NFS</acronym> Works</title>

      <para><acronym>NFS</acronym> consists of at least two main
	parts: a server and one or more clients.  The client remotely
	accesses the data that is stored on the server machine.  In
	order for this to function properly a few processes have to be
	configured and running.</para>

      <para>The server has to be running the following daemons:</para>
      <indexterm>
	<primary>NFS</primary>
	<secondary>server</secondary>
      </indexterm>
      <indexterm>
	<primary>file server</primary>
	<secondary>UNIX clients</secondary>
      </indexterm>

      <indexterm>
	<primary><application>rpcbind</application></primary>
      </indexterm>
      <indexterm>
	<primary><application>mountd</application></primary>
      </indexterm>
      <indexterm>
	<primary><application>nfsd</application></primary>
      </indexterm>

      <informaltable frame="none" pgwide="1">

	    <row>
	      <entry><application>nfsd</application></entry>
	      <entry>The <acronym>NFS</acronym> daemon which services
		requests from the <acronym>NFS</acronym>
		clients.</entry>
	    </row>
	    <row>
	      <entry><application>mountd</application></entry>

	      <entry><application>rpcbind</application></entry>
	      <entry> This daemon allows
	      <acronym>NFS</acronym> clients to discover which port
		the <acronym>NFS</acronym> server is using.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <para>The client can also run a daemon, known as
	<application>nfsiod</application>.  The
	<application>nfsiod</application> daemon services the requests
	from the <acronym>NFS</acronym> server.  This is optional, and
	improves performance, but is not required for normal and
	correct operation.  See the &man.nfsiod.8; manual page for
	more information.
      </para>
    </sect2>

    <sect2 id="network-configuring-nfs">
      <title>Configuring <acronym>NFS</acronym></title>
      <indexterm>
	<primary>NFS</primary>
	<secondary>configuration</secondary>
      </indexterm>

      <para><acronym>NFS</acronym> configuration is a relatively
	straightforward process.  The processes that need to be
	running can all start at boot time with a few modifications to
	your <filename>/etc/rc.conf</filename> file.</para>

      <para>On the <acronym>NFS</acronym> server, make sure that the
	following options are configured in the
	<filename>/etc/rc.conf</filename> file:</para>

      <programlisting>rpcbind_enable="YES"
nfs_server_enable="YES"
mountd_flags="-r"</programlisting>

      <para><application>mountd</application> runs automatically
	whenever the <acronym>NFS</acronym> server is enabled.</para>

      <para>On the client, make sure this option is present in
	<filename>/etc/rc.conf</filename>:</para>

      <programlisting>nfs_client_enable="YES"</programlisting>

      <para>The <filename>/etc/exports</filename> file specifies which
	file systems <acronym>NFS</acronym> should export (sometimes
	referred to as <quote>share</quote>).  Each line in
	<filename>/etc/exports</filename> specifies a file system to be
	exported and which machines have access to that file system.
	Along with what machines have access to that file system,
	access options may also be specified.  There are many such
	options that can be used in this file but only a few will be
	mentioned here.  You can easily discover other options by
	reading over the &man.exports.5; manual page.</para>

      <para>Here are a few example <filename>/etc/exports</filename>
	entries:</para>

      <indexterm>
	<primary>NFS</primary>
	<secondary>export examples</secondary>
      </indexterm>

      <para>The following examples give an idea of how to export
	file systems, although the settings may be different depending
	on your environment and network configuration.  For instance,
	to export the <filename>/cdrom</filename> directory to three
	example machines that have the same domain name as the server
	(hence the lack of a domain name for each) or have entries in
	your <filename>/etc/hosts</filename> file.  The
	<option>-ro</option> flag makes the exported file system
	read-only.  With this flag, the remote system will not be able
	to write any changes to the exported file system.</para>

      <programlisting>/cdrom -ro host1 host2 host3</programlisting>



      <para>One file system, <filename>/usr</filename>, has two lines
	specifying exports to the same host, <hostid>client</hostid>.
	The correct format for this situation is:</para>

      <programlisting>/usr/src /usr/ports  client</programlisting>


      <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>

      <para>or by invoking the <command>mountd</command> &man.rc.8; script
	with the appropriate parameter:</para>

      <screen>&prompt.root; <userinput>/etc/rc.d/mountd onereload</userinput></screen>


	information about using rc scripts.</para>

      <para>Alternatively, a reboot will make FreeBSD set everything
	up properly.  A reboot is not necessary though.
	Executing the following commands as <username>root</username>
	should start everything up.</para>

      <para>On the <acronym>NFS</acronym> server:</para>


	name will be <hostid>client</hostid>.  If you only want to
	temporarily mount a remote file system or would rather test the
	configuration, just execute a command like this as <username>root</username> on the
	client:</para>
      <indexterm>
	<primary>NFS</primary>
	<secondary>mounting</secondary>
      </indexterm>
      <screen>&prompt.root; <userinput>mount server:/home /mnt</userinput></screen>


	on the server at <filename>/mnt</filename> on the client.  If
	everything is set up correctly you should be able to enter
	<filename>/mnt</filename> on the client and see all the files
	that are on the server.</para>

      <para>If you want to automatically mount a remote file system
	each time the computer boots, add the file system to the

      <programlisting>server:/home	/mnt	nfs	rw	0	0</programlisting>

      <para>The &man.fstab.5; manual page lists all the available
	options.</para>
    </sect2>

    <sect2>

      <title>Practical Uses</title>

      <para><acronym>NFS</acronym> has many practical uses.  Some of
	the more common ones are listed below:</para>

      <indexterm>
	<primary>NFS</primary>
	<secondary>uses</secondary>
      </indexterm>
      <itemizedlist>
	<listitem>
	  <para>Set several machines to share a CDROM or other media
	    among them.  This is cheaper and often a more convenient
	    method to install software on multiple machines.</para>


	<listitem>
	  <para>Several machines could have a common
	    <filename>/usr/ports/distfiles</filename> directory.  That
	    way, when you need to install a port on several machines,
	    you can quickly access the source without downloading it
	    on each machine.</para>
	</listitem>
      </itemizedlist>
    </sect2>

      </sect2info>
      <title>Automatic Mounts with <application>amd</application></title>

      <indexterm>
	<primary>amd</primary>
      </indexterm>
      <indexterm>
	<primary>automatic mounter daemon</primary>
      </indexterm>

      <para>&man.amd.8; (the automatic mounter daemon)
	automatically mounts a

	<application>amd</application>.  Using
	<application>amd</application> provides a simple alternative
	to permanent mounts, as permanent mounts are usually listed in
	<filename>/etc/fstab</filename>.</para>

      <para><application>amd</application> operates by attaching
	itself as an NFS server to the <filename>/host</filename> and

      <programlisting>amd_enable="YES"</programlisting>

      <para>Additionally, custom flags can be passed to
	<application>amd</application> from the
	<varname>amd_flags</varname> option.  By default,
	<varname>amd_flags</varname> is set to:</para>

      <programlisting>amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"</programlisting>



    <sect2 id="network-nfs-integration">
      <sect2info>
	<authorgroup>
	  <author>
	    <firstname>John</firstname>
	    <surname>Lind</surname>
	    <contrib>Contributed by </contrib>
	  </author>
	</authorgroup>
      </sect2info>
      <title>Problems Integrating with Other Systems</title>


  <sect1 id="network-nis">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Bill</firstname>
	  <surname>Swingle</surname>
	  <contrib>Written by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>


    <sect2>
      <title>What Is It?</title>
      <indexterm>
	<primary>NIS</primary>
      </indexterm>
      <indexterm>
	<primary>Solaris</primary>
      </indexterm>
      <indexterm>
	<primary>HP-UX</primary>
      </indexterm>
      <indexterm>
	<primary>AIX</primary>
      </indexterm>
      <indexterm>
	<primary>Linux</primary>
      </indexterm>
      <indexterm>
	<primary>NetBSD</primary>
      </indexterm>
      <indexterm>
	<primary>OpenBSD</primary>
      </indexterm>

      <para><acronym role="Network Information System">NIS</acronym>,
	which stands for Network Information Services, was developed
	by Sun Microsystems to centralize administration of &unix;
	(originally &sunos;) systems.  It has now essentially become
	an industry standard; all major &unix; like systems
	(&solaris;, HP-UX, &aix;, Linux, NetBSD, OpenBSD, FreeBSD,
	etc) support <acronym role="Network Information
	System">NIS</acronym>.</para>

      <indexterm>
	<primary>yellow pages</primary>
	<see>NIS</see>
      </indexterm>

      <para><acronym role="Network Information System">NIS</acronym>
	was formerly known as Yellow Pages, but because of trademark

	often seen and used.</para>

      <indexterm>
	<primary>NIS</primary>
	<secondary>domains</secondary>
      </indexterm>

      <para>It is a RPC-based client/server system that allows a group

	and add, remove or modify configuration data from a single
	location.</para>

      <indexterm>
	<primary>Windows NT</primary>
      </indexterm>

      <para>It is similar to the &windowsnt; domain system; although
	the internal implementation of the two are not at all similar,
	the basic functionality can be compared.</para>
    </sect2>

    <sect2>
      <title>Terms/Processes You Should Know</title>

      <para>There are several terms and several important user
	processes that you will come across when attempting to
	implement NIS on FreeBSD, whether you are trying to create an
	NIS server or act as an NIS client:</para>

      <indexterm>
	<primary><application>rpcbind</application></primary>

	    </row>
	    <row>
	      <entry><application>ypserv</application></entry>

	      <entry>Should only be running on NIS servers; this is
		the NIS server process itself.  If &man.ypserv.8;
		dies, then the server will no longer be able to

	    </row>
	    <row>
	      <entry><application>rpc.yppasswdd</application></entry>

	      <entry>Another process that should only be running on
		NIS master servers; this is a daemon that will allow NIS
		clients to change their NIS passwords.  If this daemon

	bound to instead.</para>

      <sect3>
	<title>Machine Types</title>

	<itemizedlist>
	  <indexterm>
	    <primary>NIS</primary>
	    <secondary>master server</secondary>
	  </indexterm>
	  <listitem>
	    <para>A <emphasis>NIS master server</emphasis>.  This
	      server, analogous to a &windowsnt; primary domain
	      controller, maintains the files used by all of the NIS
	      clients.  The <filename>passwd</filename>,
	      <filename>group</filename>, and other various files used
	      by the NIS clients live on the master server.</para>

	<note><para>It is possible for one machine to be an NIS
	      master server for more than one NIS domain.  However,
	      this will not be covered in this introduction, which
	      assumes a relatively small-scale NIS
	      environment.</para></note>
	  </listitem>
	  <indexterm>
	    <primary>NIS</primary>
	    <secondary>slave server</secondary>
	  </indexterm>
	  <listitem>
	    <para><emphasis>NIS slave servers</emphasis>.  Similar to
	      the &windowsnt; backup domain controllers, NIS slave
	      servers maintain copies of the NIS master's data files.
	      NIS slave servers provide the redundancy, which is
	      needed in important environments.  They also help to
	      balance the load of the master server: NIS Clients
	      always attach to the NIS server whose response they get
	      first, and this includes slave-server-replies.</para>
	  </listitem>
	  <indexterm>
	    <primary>NIS</primary>
	    <secondary>client</secondary>
	  </indexterm>
	  <listitem>
	    <para><emphasis>NIS clients</emphasis>.  NIS clients, like
	      most &windowsnt; workstations, authenticate against the
	      NIS server (or the &windowsnt; domain controller in the
	      &windowsnt; workstations case) to log on.</para>
	  </listitem>
	</itemizedlist>
      </sect3>
    </sect2>


      <title>Using NIS/YP</title>

      <para>This section will deal with setting up a sample NIS
	environment.</para>

      <sect3>
	<title>Planning</title>

	<para>Let us assume that you are the administrator of a small
	  university lab.  This lab, which consists of 15 FreeBSD
	  machines, currently has no centralized point of
	  administration; each machine has its own
	  <filename>/etc/passwd</filename> and
	  <filename>/etc/master.passwd</filename>.  These files are
	  kept in sync with each other only through manual
	  intervention; currently, when you add a user to the lab, you
	  must run <command>adduser</command> on all 15 machines.
	  Clearly, this has to change, so you have decided to convert
	  the lab to use NIS, using two of the machines as
	  servers.</para>

	<para>Therefore, the configuration of the lab now looks something
	  like:</para>

	<informaltable frame="none" pgwide="1">
	  <tgroup cols="3">
	    <thead>
	      <row>
		<entry>Machine name</entry>
		<entry>IP address</entry>
		<entry>Machine role</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry><hostid>ellington</hostid></entry>
		<entry><hostid role="ipaddr">10.0.0.2</hostid></entry>
		<entry>NIS master</entry>
	      </row>
	      <row>
		<entry><hostid>coltrane</hostid></entry>
		<entry><hostid role="ipaddr">10.0.0.3</hostid></entry>
		<entry>NIS slave</entry>
	      </row>
	      <row>
		<entry><hostid>basie</hostid></entry>
		<entry><hostid role="ipaddr">10.0.0.4</hostid></entry>
		<entry>Faculty workstation</entry>
	      </row>
	      <row>
		<entry><hostid>bird</hostid></entry>
		<entry><hostid role="ipaddr">10.0.0.5</hostid></entry>
		<entry>Client machine</entry>
	      </row>
	      <row>
		<entry><hostid>cli[1-11]</hostid></entry>
		<entry><hostid role="ipaddr">10.0.0.[6-17]</hostid></entry>
		<entry>Other client machines</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

	<para>If you are setting up a NIS scheme for the first time, it
	  is a good idea to think through how you want to go about it.  No
	  matter what the size of your network, there are a few decisions
	  that need to be made.</para>

	<sect4>
	  <title>Choosing a NIS Domain Name</title>

	  <indexterm>
	    <primary>NIS</primary>
	    <secondary>domainname</secondary>
	  </indexterm>
	  <para>This might not be the <quote>domainname</quote> that
	    you are used to.  It is more accurately called the
	    <quote>NIS domainname</quote>.  When a client broadcasts
	    its requests for info, it includes the name of the NIS

	    assume you have chosen the name
	    <literal>test-domain</literal>.</para>

	  <indexterm>
	    <primary>SunOS</primary>
	  </indexterm>
	  <para>However, some operating systems (notably &sunos;) use
	    their NIS domain name as their Internet domain name.  If one
	    or more machines on your network have this restriction, you
	    <emphasis>must</emphasis> use the Internet domain name as
	    your NIS domain name.</para>
	</sect4>

	<sect4>
	  <title>Physical Server Requirements</title>

	  <para>There are several things to keep in mind when choosing
	    a machine to use as a NIS server.  One of the unfortunate

	    the NIS server becomes unavailable, it will affect
	    <emphasis>all</emphasis> of your NIS clients
	    adversely.</para>
	</sect4>
      </sect3>

      <sect3>
	<title>NIS Servers</title>

	<para> The canonical copies of all NIS information are stored
	  on a single machine called the NIS master server.  The

	  database file and transmitting data from the database back
	  to the client.</para>

	<sect4>
	  <title>Setting Up a NIS Master Server</title>
	  <indexterm>
	    <primary>NIS</primary>

	    <filename>/etc/rc.conf</filename>, and FreeBSD will do the
	    rest for you.</para>

	  <procedure>
	    <step>
	      <para><programlisting>nisdomainname="test-domain"</programlisting>
		This line will set the NIS domainname to
		<literal>test-domain</literal>
		upon network setup (e.g. after reboot).</para>
	    </step>
	    <step>
	      <programlisting>nis_server_enable="YES"</programlisting>
	      <para>This will tell FreeBSD to start up the NIS server processes
		when the networking is next brought up.</para>
	    </step>
	    <step>
	      <programlisting>nis_yppasswdd_enable="YES"</programlisting>
	      <para>This will enable the <command>rpc.yppasswdd</command>
		daemon which, as mentioned above, will allow users to
		change their NIS password from a client machine.</para>
	      </step>
	  </procedure>

	  <note>
	    <para>Depending on your NIS setup, you may need to add
	      further entries.  See the <link
	      linkend="network-nis-server-is-client">section about NIS
	      servers that are also NIS clients</link>, below, for
	      details.</para>
	  </note>

	  <para>After setting up the above entries, run the command
	    <command>/etc/netstart</command> as superuser.  It will
	    set up everything for you, using the values you defined in
	    <filename>/etc/rc.conf</filename>.  As a last step, before
	    initializing the NIS maps, start the
	    <application>ypserv</application> daemon manually:</para>

	  <screen>&prompt.root; <userinput>/etc/rc.d/ypserv start</userinput></screen>
	</sect4>

	<sect4>
	  <title>Initializing the NIS Maps</title>
	  <indexterm>
	    <primary>NIS</primary>
	    <secondary>maps</secondary>
	  </indexterm>
	  <para>The <emphasis>NIS maps</emphasis> are database files,
	    that are kept in the <filename>/var/yp</filename>
	    directory.  They are generated from configuration files in
	    the <filename>/etc</filename> directory of the NIS master,
	    with one exception: the
	    <filename>/etc/master.passwd</filename> file.  This is for
	    a good reason, you do not want to propagate passwords to
	    your <username>root</username> and other administrative
	    accounts to all the servers in the NIS domain.  Therefore,
	    before we initialize the NIS maps, you should:</para>

	   <screen>&prompt.root; <userinput>cp /etc/master.passwd /var/yp/master.passwd</userinput>
&prompt.root; <userinput>cd /var/yp</userinput>
&prompt.root; <userinput>vi master.passwd</userinput></screen>

	  <para>You should remove all entries regarding system
	    accounts (<username>bin</username>,
	    <username>tty</username>, <username>kmem</username>,
	    <username>games</username>, etc), as well as any accounts
	    that you do not want to be propagated to the NIS clients
	    (for example <username>root</username> and any other UID 0
	    (superuser) accounts).</para>

	  <note><para>Make sure the
	    <filename>/var/yp/master.passwd</filename> is neither group
	    nor world readable (mode 600)!  Use the
	    <command>chmod</command> command, if appropriate.</para></note>

	  <indexterm>
	    <primary>Tru64 UNIX</primary>
	  </indexterm>

	   <para>When you have finished, it is time to initialize the
	     NIS maps!  FreeBSD includes a script named
	     <command>ypinit</command> to do this for you (see its
	     manual page for more information).  Note that this script
	      is available on most &unix; Operating Systems, but not on
	     all.  On Digital UNIX/Compaq Tru64 UNIX it is called
	     <command>ypsetup</command>.  Because we are generating
	      maps for an NIS master, we are going to pass the
	     <option>-m</option> option to <command>ypinit</command>.
	     To generate the NIS maps, assuming you already performed
	     the steps above, run:</para>

	  <screen>ellington&prompt.root; <userinput>ypinit -m test-domain</userinput>
Server Type: MASTER Domain: test-domain
Creating an YP server will require that you answer a few questions.
Questions will all be asked at the beginning of the procedure.

NIS Map update completed.
ellington has been setup as an YP master server without any errors.</screen>

	  <para><command>ypinit</command> should have created
	    <filename>/var/yp/Makefile</filename> from
	    <filename>/var/yp/Makefile.dist</filename>.
	    When created, this file assumes that you are operating
	    in a single server NIS environment with only FreeBSD
	    machines.  Since <literal>test-domain</literal> has
	    a slave server as well, you must edit
	    <filename>/var/yp/Makefile</filename>:</para>

	  <screen>ellington&prompt.root; <userinput>vi /var/yp/Makefile</userinput></screen>

	  <para>You should comment out the line that says</para>

	  <programlisting>NOPUSH = "True"</programlisting>

	  <para>(if it is not commented out already).</para>
	</sect4>

	<sect4>
	  <title>Setting up a NIS Slave Server</title>
	  <indexterm>
	    <primary>NIS</primary>

	  </indexterm>
	  <para>Setting up an NIS slave server is even more simple than
	    setting up the master.  Log on to the slave server and edit the
	    file <filename>/etc/rc.conf</filename> as you did before.
	    The only difference is that we now must use the
	    <option>-s</option> option when running <command>ypinit</command>.
	    The <option>-s</option> option requires the name of the NIS
	    master be passed to it as well, so our command line looks
	    like:</para>

	  <screen>coltrane&prompt.root; <userinput>ypinit -s ellington test-domain</userinput>

Server Type: SLAVE Domain: test-domain Master: ellington


	    is especially important on busy networks where map updates
	    might not always complete.</para>

	  <para>Now, run the command <command>/etc/netstart</command> on the
	    slave server as well, which again starts the NIS server.</para>
	</sect4>
      </sect3>

      <sect3>
	<title>NIS Clients</title>

	<para> An NIS client establishes what is called a binding to a
	  particular NIS server using the

	  <procedure>
	    <step>
	      <para>Edit the file <filename>/etc/rc.conf</filename> and
		add the following lines in order to set the NIS domainname
		and start <command>ypbind</command> upon network
		startup:</para>

	      <programlisting>nisdomainname="test-domain"
nis_client_enable="YES"</programlisting>

		server, remove all user accounts from your
		<filename>/etc/master.passwd</filename> file and use
		<command>vipw</command> to add the following line to
		the end of the file:</para>

	      <programlisting>+:::::::::</programlisting>


		  many ways to configure your NIS client by changing this
		  line.  See the <link linkend="network-netgroups">netgroups
		  section</link> below for more information.
		   For more detailed reading see O'Reilly's book on
		  <literal>Managing NFS and NIS</literal>.</para>
	      </note>

	      <note>
		<para>You should keep at least one local account (i.e.
		   not imported via NIS) in your
		  <filename>/etc/master.passwd</filename> and this
		  account should also be a member of the group
		  <groupname>wheel</groupname>.  If there is something
		  wrong with NIS, this account can be used to log in
		  remotely, become <username>root</username>, and fix things.</para>
	      </note>
	    </step>

	    <step>
	      <para>To import all possible group entries from the NIS

	<filename>/var/yp/securenets</filename>.</para>

      <note>
	<para>While both of these access control mechanisms provide some
	  security, they, like the privileged port test, are
	  vulnerable to <quote>IP spoofing</quote> attacks.  All
	  NIS-related traffic should be blocked at your firewall.</para>

	<para>Servers using <filename>/var/yp/securenets</filename>
	  may fail to serve legitimate NIS clients with archaic TCP/IP
	  implementations.  Some of these implementations set all
	  host bits to zero when doing broadcasts and/or fail to
	  observe the subnet mask when calculating the broadcast
	  address.  While some of these problems can be fixed by
	  changing the client configuration, other problems may force
	  the retirement of the client systems in question or the
	  abandonment of <filename>/var/yp/securenets</filename>.</para>

	<para>Using <filename>/var/yp/securenets</filename> on a
	  server with such an archaic implementation of TCP/IP is a
	  really bad idea and will lead to loss of NIS functionality
	  for large parts of your network.</para>

	<indexterm>
	  <primary>TCP Wrappers</primary>
	</indexterm>
	<para>The use of the <application>TCP Wrapper</application>
	  package increases the latency of your NIS server.  The
	  additional delay may be long enough to cause timeouts in
	  client programs, especially in busy networks or with slow
	  NIS servers.  If one or more of your client systems
	  suffers from these symptoms, you should convert the client
	  systems in question into NIS slave servers and force them
	  to bind to themselves.</para>
      </note>
    </sect2>


      <title>Barring Some Users from Logging On</title>

      <para>In our lab, there is a machine <hostid>basie</hostid> that
	is supposed to be a faculty only workstation.  We do not want
	to take this machine out of the NIS domain, yet the
	<filename>passwd</filename> file on the master NIS server
	contains accounts for both faculty and students.  What can we
	do?</para>

      <para>There is a way to bar specific users from logging on to a
	machine, even if they are present in the NIS database.  To do
	this, all you must do is add
	<literal>-<replaceable>username</replaceable></literal> to the
	end of the <filename>/etc/master.passwd</filename> file on the
	client machine, where <replaceable>username</replaceable> is
	the username of the user you wish to bar from logging in.
	This should preferably be done using <command>vipw</command>,
	since <command>vipw</command> will sanity check your changes
	to <filename>/etc/master.passwd</filename>, as well as
	automatically rebuild the password database when you finish
	editing.  For example, if we wanted to bar user
	<username>bill</username> from logging on to
	<hostid>basie</hostid> we would:</para>

      <screen>basie&prompt.root; <userinput>vipw</userinput>
<userinput>[add -bill to the end, exit]</userinput>
vipw: rebuilding the database...
vipw: done


    <sect2 id="network-netgroups">
      <sect2info>
	<authorgroup>
	  <author>
	    <firstname>Udo</firstname>
	    <surname>Erdelhoff</surname>
	    <contrib>Contributed by </contrib>
	  </author>
	</authorgroup>
      </sect2info>

      <title>Using Netgroups</title>
      <indexterm>
	<primary>netgroups</primary>
      </indexterm>

      <para>The method shown in the previous section works reasonably
	well if you need special rules for a very small number of
	users and/or machines.  On larger networks, you
	<emphasis>will</emphasis> forget to bar some users from logging
	onto sensitive machines, or you may even have to modify each
	machine separately, thus losing the main benefit of NIS:
	<emphasis>centralized</emphasis> administration.</para>

      <para>The NIS developers' solution for this problem is called
	<emphasis>netgroups</emphasis>.  Their purpose and semantics
	can be compared to the normal groups used by &unix; file
	systems.  The main differences are the lack of a numeric ID
	and the ability to define a netgroup by including both user
	accounts and other netgroups.</para>

      <para>Netgroups were developed to handle large, complex networks
	with hundreds of users and machines.  On one hand, this is
	a Good Thing if you are forced to deal with such a situation.
	On the other hand, this complexity makes it almost impossible to
	explain netgroups with really simple examples.  The example
	used in the remainder of this section demonstrates this
	problem.</para>

      <para>Let us assume that your successful introduction of NIS in
	your laboratory caught your superiors' interest.  Your next
	job is to extend your NIS domain to cover some of the other
	machines on campus.  The two tables contain the names of the
	new users and new machines as well as brief descriptions of
	them.</para>

      <informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	  <thead>
	    <row>
	      <entry>User Name(s)</entry>
	      <entry>Description</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry><username>alpha</username>, <username>beta</username></entry>
	      <entry>Normal employees of the IT department</entry>
	    </row>

	    <row>
	      <entry><username>charlie</username>, <username>delta</username></entry>
	      <entry>The new apprentices of the IT department</entry>
	    </row>

	    <row>
	      <entry><username>echo</username>, <username>foxtrott</username>, <username>golf</username>, ...</entry>
	      <entry>Ordinary employees</entry>
	    </row>

	    <row>
	      <entry><username>able</username>, <username>baker</username>, ...</entry>
	      <entry>The current interns</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	  <thead>
	    <row>
	      <entry>Machine Name(s)</entry>
	      <entry>Description</entry>
	    </row>
	  </thead>

	<tbody>
	    <row>
	      <!--  Names taken from "Good Omens" by Neil Gaiman and Terry
		    Pratchett.  Many thanks for a brilliant book.  -->

	      <entry><hostid>war</hostid>, <hostid>death</hostid>,
		<hostid>famine</hostid>,
		<hostid>pollution</hostid></entry>
	      <entry>Your most important servers.  Only the IT
		employees are allowed to log onto these
		machines.</entry>
	     </row>
	    <row>
              <!-- gluttony was omitted because it was too fat -->

	      <entry><hostid>pride</hostid>, <hostid>greed</hostid>,
		<hostid>envy</hostid>, <hostid>wrath</hostid>,
		<hostid>lust</hostid>, <hostid>sloth</hostid></entry>
	      <entry>Less important servers.  All members of the IT
		department are allowed to login onto these
		machines.</entry>
	     </row>

	    <row>
	      <entry><hostid>one</hostid>, <hostid>two</hostid>,
		<hostid>three</hostid>, <hostid>four</hostid>,
		...</entry>

	      <entry>Ordinary workstations.  Only the
		<emphasis>real</emphasis> employees are allowed to use
		these machines.</entry>
	     </row>

	    <row>
	      <entry><hostid>trashcan</hostid></entry>
	      <entry>A very old machine without any critical data.
		Even the intern is allowed to use this box.</entry>
	     </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <para>If you tried to implement these restrictions by separately
	blocking each user, you would have to add one
	<literal>-<replaceable>user</replaceable></literal> line to
	each system's <filename>passwd</filename> for each user who is
	not allowed to login onto that system.  If you forget just one
	entry, you could be in trouble.  It may be feasible to do this
	correctly during the initial setup, however you
	<emphasis>will</emphasis> eventually forget to add the lines
	for new users during day-to-day operations.  After all, Murphy
	was an optimist.</para>

      <para>Handling this situation with netgroups offers several
	advantages.  Each user need not be handled separately; you
	assign a user to one or more netgroups and allow or forbid
	logins for all members of the netgroup.  If you add a new
	machine, you will only have to define login restrictions for
	netgroups.  If a new user is added, you will only have to add
	the user to one or more netgroups.  Those changes are
	independent of each other: no more <quote>for each combination
	of user and machine do...</quote> If your NIS setup is planned
	carefully, you will only have to modify exactly one central
	configuration file to grant or deny access to machines.</para>

      <para>The first step is the initialization of the NIS map
	netgroup.  FreeBSD's &man.ypinit.8; does not create this map by
	default, but its NIS implementation will support it once it has
	been created.  To create an empty map, simply type</para>

      <screen>ellington&prompt.root; <userinput>vi /var/yp/netgroup</userinput></screen>

      <para>and start adding content.  For our example, we need at
	least four netgroups: IT employees, IT apprentices, normal
	employees and interns.</para>

      <programlisting>IT_EMP  (,alpha,test-domain)    (,beta,test-domain)
IT_APP  (,charlie,test-domain)  (,delta,test-domain)

INTERNS (,able,test-domain)     (,baker,test-domain)</programlisting>

      <para><literal>IT_EMP</literal>, <literal>IT_APP</literal> etc.
	are the names of the netgroups.  Each bracketed group adds
	one or more user accounts to it.  The three fields inside a
	group are:</para>

      <orderedlist>
	<listitem>
	  <para>The name of the host(s) where the following items are
	    valid.  If you do not specify a hostname, the entry is
	    valid on all hosts.  If you do specify a hostname, you
	    will enter a realm of darkness, horror and utter confusion.</para>
	</listitem>

	<listitem>
	  <para>The name of the account that belongs to this
	    netgroup.</para>
	</listitem>

	<listitem>
	  <para>The NIS domain for the account.  You can import
	    accounts from other NIS domains into your netgroup if you
	    are one of the unlucky fellows with more than one NIS
	    domain.</para>
	</listitem>
      </orderedlist>

      <para>Each of these fields can contain wildcards.  See
	&man.netgroup.5; for details.</para>

      <note>
	<indexterm>
	  <primary>netgroups</primary>
	</indexterm>
	<para>Netgroup names longer than 8 characters should not be
	  used, especially if you have machines running other
	  operating systems within your NIS domain.  The names are
	  case sensitive; using capital letters for your netgroup
	  names is an easy way to distinguish between user, machine
	  and netgroup names.</para>

	<para>Some NIS clients (other than FreeBSD) cannot handle
	  netgroups with a large number of entries.  For example, some
	  older versions of &sunos; start to cause trouble if a netgroup
	  contains more than 15 <emphasis>entries</emphasis>.  You can
	  circumvent this limit by creating several sub-netgroups with
	  15 users or less and a real netgroup that consists of the
	  sub-netgroups:</para>

	<programlisting>BIGGRP1  (,joe1,domain)  (,joe2,domain)  (,joe3,domain) [...]
BIGGRP2  (,joe16,domain)  (,joe17,domain) [...]
BIGGRP3  (,joe31,domain)  (,joe32,domain)
BIGGROUP  BIGGRP1 BIGGRP2 BIGGRP3</programlisting>

	<para>You can repeat this process if you need more than 225
	  users within a single netgroup.</para>
      </note>

      <para>Activating and distributing your new NIS map is
	easy:</para>

      <screen>ellington&prompt.root; <userinput>cd /var/yp</userinput>
ellington&prompt.root; <userinput>make</userinput></screen>

      <para>This will generate the three NIS maps
	<filename>netgroup</filename>,
	<filename>netgroup.byhost</filename> and
	<filename>netgroup.byuser</filename>.  Use &man.ypcat.1; to
	check if your new NIS maps are available:</para>

      <screen>ellington&prompt.user; <userinput>ypcat -k netgroup</userinput>
ellington&prompt.user; <userinput>ypcat -k netgroup.byhost</userinput>
ellington&prompt.user; <userinput>ypcat -k netgroup.byuser</userinput></screen>

      <para>The output of the first command should resemble the
	contents of <filename>/var/yp/netgroup</filename>.  The second
	command will not produce output if you have not specified
	host-specific netgroups.  The third command can be used to
	get the list of netgroups for a user.</para>

      <para>The client setup is quite simple.  To configure the server
	<hostid>war</hostid>, you only have to start
	&man.vipw.8; and replace the line</para>

      <programlisting>+:::::::::</programlisting>


      <programlisting>+@IT_EMP:::::::::</programlisting>

      <para>Now, only the data for the users defined in the netgroup
	<literal>IT_EMP</literal> is imported into
	<hostid>war</hostid>'s password database and only
	these users are allowed to login.</para>

      <para>Unfortunately, this limitation also applies to the
	<literal>~</literal> function of the shell and all routines

	servers</emphasis>.</para>

      <para>This can be achieved by adding another line to
	<filename>/etc/master.passwd</filename>.  This line should
	contain:</para>

      <para><literal>+:::::::::/sbin/nologin</literal>, meaning
	<quote>Import all entries but replace the shell with
	<filename>/sbin/nologin</filename> in the imported
	entries</quote>.  You can replace any field in the
	<literal>passwd</literal> entry by placing a default value in
	your <filename>/etc/master.passwd</filename>.</para>

      <!-- Been there, done that, got the scars to prove it - ue -->
      <warning>
	<para>Make sure that the line
	<literal>+:::::::::/sbin/nologin</literal> is placed after
	<literal>+@IT_EMP:::::::::</literal>.  Otherwise, all user
	accounts imported from NIS will have <filename>/sbin/nologin</filename> as their
	login shell.</para>
      </warning>

      <para>After this change, you will only have to change one NIS
	map if a new employee joins the IT department.  You could use
	a similar approach for the less important servers by replacing
	the old <literal>+:::::::::</literal> in their local version
	of <filename>/etc/master.passwd</filename> with something like
	this:</para>

      <programlisting>+@IT_EMP:::::::::
+@IT_APP:::::::::
+:::::::::/sbin/nologin</programlisting>

      <para>The corresponding lines for the normal workstations
	could be:</para>

      <programlisting>+@IT_EMP:::::::::
+@USERS:::::::::
+:::::::::/sbin/nologin</programlisting>

      <para>And everything would be fine until there is a policy
	change a few weeks later: The IT department starts hiring
	interns.  The IT interns are allowed to use the normal
	workstations and the less important servers; and the IT
	apprentices are allowed to login onto the main servers.  You
	add a new netgroup <literal>IT_INTERN</literal>, add the new
	IT interns to this netgroup and start to change the
	configuration on each and every machine...  As the old saying
	goes: <quote>Errors in centralized planning lead to global
	mess</quote>.</para>

      <para>NIS' ability to create netgroups from other netgroups can
	be used to prevent situations like these.  One possibility
	is the creation of role-based netgroups.  For example, you
	could create a netgroup called
	<literal>BIGSRV</literal> to define the login
	restrictions for the important servers, another netgroup
	called <literal>SMALLSRV</literal> for the less
	important servers and a third netgroup called
	<literal>USERBOX</literal> for the normal
	workstations.  Each of these netgroups contains the netgroups
	that are allowed to login onto these machines.  The new
	entries for your NIS map netgroup should look like this:</para>

      <programlisting>BIGSRV    IT_EMP  IT_APP
SMALLSRV  IT_EMP  IT_APP  ITINTERN
USERBOX   IT_EMP  ITINTERN USERS</programlisting>

      <para>This method of defining login restrictions works
	reasonably well if you can define groups of machines with
	identical restrictions.  Unfortunately, this is the exception
	and not the rule.  Most of the time, you will need the ability
	to define login restrictions on a per-machine basis.</para>

      <para>Machine-specific netgroup definitions are the other
	possibility to deal with the policy change outlined above.  In
	this scenario, the <filename>/etc/master.passwd</filename> of
	each box contains two lines starting with <quote>+</quote>.
	The first of them adds a netgroup with the accounts allowed to
	login onto this machine, the second one adds all other
	accounts with <filename>/sbin/nologin</filename> as shell.  It
	is a good idea to use the <quote>ALL-CAPS</quote> version of
	the machine name as the name of the netgroup.  In other words,
	the lines should look like this:</para>

      <programlisting>+@<replaceable>BOXNAME</replaceable>:::::::::
+:::::::::/sbin/nologin</programlisting>

      <para>Once you have completed this task for all your machines,
	you will not have to modify the local versions of
	<filename>/etc/master.passwd</filename> ever again.  All
	further changes can be handled by modifying the NIS map.  Here
	is an example of a possible netgroup map for this
	scenario with some additional goodies:</para>

      <programlisting># Define groups of users first
IT_EMP    (,alpha,test-domain)    (,beta,test-domain)

# [...more groups to follow]</programlisting>

      <para>If you are using some kind of database to manage your user
	accounts, you should be able to create the first part of the
	map with your database's report tools.  This way, new users
	will automatically have access to the boxes.</para>

      <para>One last word of caution: It may not always be advisable
	to use machine-based netgroups.  If you are deploying a couple of
	dozen or even hundreds of identical machines for student labs,
	you should use role-based netgroups instead of machine-based
	netgroups to keep the size of the NIS map within reasonable
	limits.</para>
    </sect2>

    <sect2>
      <title>Important Things to Remember</title>

      <para>There are still a couple of things that you will need to do
	differently now that you are in an NIS environment.</para>

      <itemizedlist>
	<listitem>
	  <para>Every time you wish to add a user to the lab, you
	    must add it to the master NIS server <emphasis>only</emphasis>,
	    and <emphasis>you must remember to rebuild the NIS
	    maps</emphasis>.  If you forget to do this, the new user will
	    not be able to login anywhere except on the NIS master.
	    For example, if we needed to add a new user
	    <username>jsmith</username> to the lab, we would:</para>

	   <screen>&prompt.root; <userinput>pw useradd jsmith</userinput>
&prompt.root; <userinput>cd /var/yp</userinput>
&prompt.root; <userinput>make test-domain</userinput></screen>

	  <para>You could also run <command>adduser jsmith</command> instead
	    of <command>pw useradd jsmith</command>.</para>
	</listitem>
	<listitem>
	  <para><emphasis>Keep the administration accounts out of the
	    NIS maps</emphasis>.  You do not want to be propagating
	    administrative accounts and passwords to machines that
	    will have users that should not have access to those
	    accounts.</para>
	</listitem>
	<listitem>
	  <para><emphasis>Keep the NIS master and slave secure, and
	    minimize their downtime</emphasis>.  If somebody either
	    hacks or simply turns off these machines, they have
	    effectively rendered many people without the ability to
	    login to the lab.</para>

	  <para>This is the chief weakness of any centralized administration
	    system.  If you do
	    not protect your NIS servers, you will have a lot of angry
	    users!</para>
	</listitem>
      </itemizedlist>
    </sect2>


      <para>You can force a host to bind to a particular server by running
	<command>ypbind</command> with the <option>-S</option>
	flag.  If you do not want to do this manually each time you
	reboot your NIS server, you can add the following lines to
	your <filename>/etc/rc.conf</filename>:</para>

      <programlisting>nis_client_enable="YES"	# run client stuff as well
nis_client_flags="-S <replaceable>NIS domain</replaceable>,<replaceable>server</replaceable>"</programlisting>

    <sect2>
      <title>Password Formats</title>
      <indexterm>
	<primary>NIS</primary>
	<secondary>password formats</secondary>
      </indexterm>
      <para>One of the most common issues that people run into when trying


      <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen>

      <note>
	<para>The format of passwords already in
	  <filename>/etc/master.passwd</filename> will not be updated
	  until a user changes his password for the first time
	  <emphasis>after</emphasis> the login capability database is
	  rebuilt.</para>
      </note>

      <para>Next, in order to ensure that passwords are encrypted with
	the format that you have chosen, you should also check that

  <sect1 id="network-dhcp">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Greg</firstname>
	  <surname>Sutter</surname>
	  <contrib>Written by </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>Automatic Network Configuration (DHCP)</title>

    <sect2>
      <title>What Is DHCP?</title>
      <indexterm>
	<primary>Dynamic Host Configuration Protocol</primary>
	<see>DHCP</see>
      </indexterm>
      <indexterm>
	<primary>Internet Systems Consortium (ISC)</primary>
      </indexterm>

      <para>DHCP, the Dynamic Host Configuration Protocol, describes
	the means by which a system can connect to a network and obtain the
	necessary information for communication upon that network.  FreeBSD
	uses the OpenBSD <command>dhclient</command>
	taken from OpenBSD&nbsp;3.7.  All
	information here regarding <command>dhclient</command> is for

    <sect2>
      <title>What This Section Covers</title>

      <para>This section describes both the client-side components 
	of the ISC and OpenBSD DHCP client and
	server-side components of the ISC DHCP system.  The
	client-side program, <command>dhclient</command>, comes
	integrated within FreeBSD, and the server-side portion is
	available from the <filename
	role="package">net/isc-dhcp31-server</filename> port.  The
	&man.dhclient.8;, &man.dhcp-options.5;, and
	&man.dhclient.conf.5; manual pages, in addition to the
	references below, are useful resources.</para>
    </sect2>

    <sect2>
      <title>How It Works</title>
      <indexterm>
	<primary>UDP</primary>
      </indexterm>
      <para>When <command>dhclient</command>, the DHCP client, is
	executed on the client machine, it begins broadcasting
	requests for configuration information.  By default, these

	network can be automatically reclaimed.</para>

      <para>DHCP clients can obtain a great deal of information from
	the server.  An exhaustive list may be found in
	&man.dhcp-options.5;.</para>
    </sect2>

    <sect2>
      <title>FreeBSD Integration</title>

      <para>&os; fully integrates the OpenBSD DHCP client,
	<command>dhclient</command>.  DHCP client support is provided
	within both the installer and the base system, obviating the need
	for detailed knowledge of network configurations on any network
	that runs a DHCP server.</para>
	<indexterm>
	  <primary><application>sysinstall</application></primary>
	</indexterm>

      <para>DHCP is supported by
	<application>sysinstall</application>.  When configuring a
	network interface within
	<application>sysinstall</application>, the second question
	asked is: <quote>Do you want to try DHCP configuration of
	the interface?</quote>. Answering affirmatively will
	execute <command>dhclient</command>, and if successful, will
	fill in the network configuration information
	automatically.</para>

      <para>There are two things you must do to have your system use
	DHCP upon startup:</para>
      <indexterm>
	<primary>DHCP</primary>
	<secondary>requirements</secondary>
      </indexterm>
      <itemizedlist>
	<listitem>
	  <para>Make sure that the <devicename>bpf</devicename>
	    device is compiled into your kernel.  To do this, add
	    <literal>device bpf</literal> to your kernel
	    configuration file, and rebuild the kernel.  For more
	    information about building kernels, see <xref
	    linkend="kernelconfig">.</para> <para>The
	    <devicename>bpf</devicename> device is already part of
	    the <filename>GENERIC</filename> kernel that is supplied
	    with FreeBSD, so if you do not have a custom kernel, you
	    should not need to create one in order to get DHCP
	    working.</para>
	  <note>
	    <para>For those who are particularly security conscious,
	      you should be warned that <devicename>bpf</devicename>
	      is also the device that allows packet sniffers to work
	      correctly (although they still have to be run as
	      <username>root</username>).  <devicename>bpf</devicename>
	      <emphasis>is</emphasis> required to use DHCP, but if
	      you are very sensitive about security, you probably
	      should not add <devicename>bpf</devicename> to your
	      kernel in the expectation that at some point in the
	      future you will be using DHCP.</para>
	  </note>
	</listitem>
	<listitem>
	  <para>Edit your <filename>/etc/rc.conf</filename> to
	    include the following:</para>

	  <programlisting>ifconfig_fxp0="DHCP"</programlisting>

	  <note>
	    <para>Be sure to replace <literal>fxp0</literal> with the
	      designation for the interface that you wish to dynamically
	      configure, as described in
	      <xref linkend="config-network-setup">.</para>
	  </note>

	  <para>If you are using a different location for
	    <command>dhclient</command>, or if you wish to pass additional
	    flags to <command>dhclient</command>, also include the
	    following (editing as necessary):</para>

	  <programlisting>dhclient_program="/sbin/dhclient"
dhclient_flags=""</programlisting>
	</listitem>
      </itemizedlist>

      <indexterm>
	<primary>DHCP</primary>
	<secondary>server</secondary>
      </indexterm>
      <para>The DHCP server, <application>dhcpd</application>, is included
	as part of the <filename
	role="package">net/isc-dhcp31-server</filename> port in the ports
	collection.  This port contains the ISC DHCP server and
	documentation.</para>
    </sect2>

    <sect2>
      <title>Files</title>
      <indexterm>
	<primary>DHCP</primary>
	<secondary>configuration files</secondary>
      </indexterm>
      <itemizedlist>
	<listitem>
	  <para><filename>/etc/dhclient.conf</filename></para>
	  <para><command>dhclient</command> requires a configuration file,
	    <filename>/etc/dhclient.conf</filename>.  Typically the file
	    contains only comments, the defaults being reasonably sane.  This
	    configuration file is described by the &man.dhclient.conf.5;
	    manual page.</para>
	</listitem>

	<listitem>
	  <para><filename>/sbin/dhclient</filename></para>
	<para><command>dhclient</command> is statically linked and
	    resides in <filename>/sbin</filename>.  The &man.dhclient.8;
	    manual page gives more information about
	    <command>dhclient</command>.</para>
	</listitem>

	<listitem>
	  <para><filename>/sbin/dhclient-script</filename></para>
	  <para><command>dhclient-script</command> is the FreeBSD-specific
	    DHCP client configuration script.  It is described in
	    &man.dhclient-script.8;, but should not need any user
	    modification to function properly.</para>
	</listitem>

        <listitem>
	  <para><filename>/var/db/dhclient.leases</filename></para>
	   <para>The DHCP client keeps a database of valid leases in this
	    file, which is written as a log.  &man.dhclient.leases.5;
	    gives a slightly longer description.</para>
	</listitem>
      </itemizedlist>
    </sect2>


      <title>Further Reading</title>

      <para>The DHCP protocol is fully described in
	<ulink url="http://www.freesoft.org/CIE/RFC/2131/">RFC 2131</ulink>.
	An informational resource has also been set up at
	<ulink url="http://www.dhcp.org/"></ulink>.</para>
    </sect2>

    <sect2 id="network-dhcp-server">

	    supplied with FreeBSD, so you do not need to create a custom
	    kernel in order to get DHCP working.</para>

	  <note>
	    <para>Those who are particularly security conscious
	      should note that <devicename>bpf</devicename>
	      is also the device that allows packet sniffers to work
	      correctly (although such programs still need privileged
	      access).  <devicename>bpf</devicename>
	      <emphasis>is</emphasis> required to use DHCP, but if
	      you are very sensitive about security, you probably
	      should not include <devicename>bpf</devicename> in your
	      kernel purely because you expect to use DHCP at some
	      point in the future.</para>
	  </note>

	  <para>The next thing that you will need to do is edit the sample
	    <filename>dhcpd.conf</filename> which was installed by the

	    <secondary>configuration files</secondary>
	  </indexterm>
	  <itemizedlist>
	    <listitem>
	      <para><filename>/usr/local/sbin/dhcpd</filename></para>
	      <para><application>dhcpd</application> is statically linked and
		resides in <filename>/usr/local/sbin</filename>.  The
		&man.dhcpd.8; manual page installed with the

		<application>dhcpd</application>.</para>
	    </listitem>

	    <listitem>
	      <para><filename>/usr/local/etc/dhcpd.conf</filename></para>
	      <para><application>dhcpd</application> requires a configuration
		file, <filename>/usr/local/etc/dhcpd.conf</filename> before it
		will start providing service to clients.  This file needs to

		by the port.</para>
	    </listitem>

	    <listitem>
	      <para><filename>/var/db/dhcpd.leases</filename></para>
	      <para>The DHCP server keeps a database of leases it has issued
		in this file, which is written as a log.  The manual page
		&man.dhcpd.leases.5;, installed by the port
		gives a slightly longer description.</para>
	    </listitem>

	    <listitem>
	      <para><filename>/usr/local/sbin/dhcrelay</filename></para>
	      <para><application>dhcrelay</application> is used in advanced
		environments where one DHCP server forwards a request from a
		client to another DHCP server on a separate network.  If you

  <sect1 id="network-dns">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Chern</firstname>
	  <surname>Lee</surname>
	  <contrib>Contributed by </contrib>
	</author>

	<author>
	  <firstname>Tom</firstname>


    <sect2>
      <title>Overview</title>
      <indexterm>
	<primary>BIND</primary>
      </indexterm>

      <para>&os; utilizes, by default, a version of BIND (Berkeley
	Internet Name Domain), which is the most common implementation

	installation provides enhanced security features, a new file
	system layout and automated &man.chroot.8; configuration.</para>

      <indexterm>
	<primary>DNS</primary>
      </indexterm>
      <para><acronym>DNS</acronym> is coordinated across the Internet
	through a somewhat complex system of authoritative root, Top
	Level Domain (<acronym>TLD</acronym>), and other smaller-scale

      <para>To understand this document, some terms related to
	<acronym>DNS</acronym> must be understood.</para>

      <indexterm>
	<primary>resolver</primary>
      </indexterm>
      <indexterm>
	<primary>reverse DNS</primary>
      </indexterm>
      <indexterm>
	<primary>root zone</primary>
      </indexterm>

      <informaltable frame="none" pgwide="1">
	<tgroup cols="2">

      <screen>&prompt.root; <userinput>/etc/rc.d/named onestart</userinput></screen>

      <para>To ensure the <application>named</application> daemon is
	started at boot each time, put the following line into the
	<filename>/etc/rc.conf</filename>:</para>

      <programlisting>named_enable="YES"</programlisting>


; Aliases
www             IN      CNAME   example.org.</programlisting>

	<para>Note that every hostname ending in a <quote>.</quote> is an
	  exact hostname, whereas everything without a trailing
	   <quote>.</quote> is relative to the origin.  For example,
	  <literal>ns1</literal> is translated into
	  <literal>ns1.<replaceable>example.org.</replaceable></literal></para>

	<para>The format of a zone file follows:</para>

	<programlisting>recordname      IN recordtype   value</programlisting>

	<indexterm>
	  <primary>DNS</primary>
	  <secondary>records</secondary>
	</indexterm>

	<para>The most commonly used DNS records:</para>

	<variablelist>
	  <varlistentry>
	    <term>SOA</term>

	    <listitem>
	      <para>start of zone authority</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>NS</term>

	    <listitem>
	      <para>an authoritative name server</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>A</term>

	    <listitem>
	      <para>a host address</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>CNAME</term>

	    <listitem>
	      <para>the canonical name for an alias</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>MX</term>

	    <listitem>
	      <para>mail exchanger</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>PTR</term>

	    <listitem>
	      <para>a domain name pointer (used in reverse DNS)</para>
	    </listitem>
	  </varlistentry>
	</variablelist>

	<programlisting>example.org. IN SOA ns1.example.org. admin.example.org. (
                        2006051501      ; Serial
                        10800           ; Refresh after 3 hours
                        3600            ; Retry after 1 hour

	  </varlistentry>
	</variablelist>

	<programlisting>       IN NS           ns1.example.org.</programlisting>

	<para>This is an NS entry.  Every name server that is going to reply
	  authoritatively for the zone must have one of these entries.</para>

	<programlisting>localhost       IN      A       127.0.0.1
ns1             IN      A       192.168.1.2
ns2             IN      A       192.168.1.3
mx              IN      A       192.168.1.4
mail            IN      A       192.168.1.5</programlisting>

	<para>The A record indicates machine names.  As seen above,
	  <hostid role="fqdn">ns1.example.org</hostid> would resolve
	  to <hostid role="ipaddr">192.168.1.2</hostid>.</para>

	<programlisting>                IN      A       192.168.1.1</programlisting>

	<para>This line assigns IP address
	  <hostid role="ipaddr">192.168.1.1</hostid> to the current origin,
	  in this case <hostid role="domainname">example.org</hostid>.</para>

	<programlisting>www             IN CNAME        @</programlisting>

	<para>The canonical name record is usually used for giving aliases
	  to a machine.  In the example, <hostid>www</hostid> is
	  aliased to the <quote>master</quote> machine whose name happens
	  to be the same as the domain name
	  <hostid role="domainname">example.org</hostid>
	  (<hostid role="ipaddr">192.168.1.1</hostid>).
	  CNAMEs can never be used together with another kind of record
	  for the same hostname.</para>

	<indexterm>
	  <primary>MX record</primary>
	</indexterm>

	<programlisting>               IN MX   10      mail.example.org.</programlisting>

	<para>The MX record indicates which mail
	  servers are responsible for handling incoming mail for the
	  zone.  <hostid role="fqdn">mail.example.org</hostid> is the
	  hostname of a mail server, and 10 is the priority of
	  that mail server.</para>

	<para>One can have several mail servers, with priorities of 10,
	  20 and so on.  A mail server attempting to deliver to <hostid
	  role="domainname">example.org</hostid> would first try the
	  highest priority MX (the record with the lowest priority
	  number), then the second highest, etc, until the mail can be
	  properly delivered.</para>

	<para>For in-addr.arpa zone files (reverse DNS), the same format is
	  used, except with PTR entries instead of  A or CNAME.</para>
	  A or CNAME.</para>

	<programlisting>$TTL 3600

1.168.192.in-addr.arpa. IN SOA ns1.example.org. admin.example.org. (
                        2006051501      ; Serial

4       IN      PTR     mx.example.org.
5       IN      PTR     mail.example.org.</programlisting>

	<para>This file gives the proper IP address to hostname
	  mappings for the above fictitious domain.</para>

	<para>It is worth noting that all names on the right side
	  of a PTR record need to be fully qualified (i.e., end in

    <sect2>
      <title>Caching Name Server</title>
      <indexterm>
	<primary>BIND</primary>
	<secondary>caching name server</secondary>
      </indexterm>

      <para>A caching name server is a name server whose primary role
	is to resolve recursive queries.  It simply asks queries of its
	own, and remembers the answers for later use.</para>
    </sect2>

    <sect2>
      <title><acronym
	role="Doman Name Security Extensions">DNSSEC</acronym></title>
      <indexterm>
	<primary>BIND</primary>
	<secondary>DNS security extensions</secondary>
      </indexterm>

      <para>Domain Name System Security Extensions, or <acronym
	role="Domain Name Security Extensions">DNSSEC</acronym> for short, is a
	suite of specifications to protect resolving name servers from forged 
	<acronym>DNS</acronym> data, such as spoofed <acronym>DNS</acronym>
	records.  By using digital signatures, a resolver can verify the 
	integrity of the record.  Note that <acronym
	role="Domain Name Security Extensions">DNSSEC</acronym> only provides 
	integrity via digitally signing the Resource Records (<acronym 
	role="Resource Record">RR</acronym>s).  It provides neither
	confidentiality nor protection against false end-user assumptions.
	This means that it cannot protect against people going to <hostid
	role="domainname">example.net</hostid> instead of <hostid
	role="domainname">example.com</hostid>.  The only thing
	<acronym>DNSSEC</acronym> does is authenticate that the data has not
	been compromised in transit.  The security of <acronym>DNS</acronym> is 
	an important step in securing the Internet in general.  For more
	in-depth details of how <acronym>DNSSEC</acronym> works, the relevant
	<acronym>RFC</acronym>s are a good place to start.  See the list in
	<xref linkend="dns-read">.</para>

      <para>The following sections will demonstrate how to enable
	<acronym>DNSSEC</acronym> for an authoritative <acronym>DNS</acronym>
	server and a recursive (or caching) <acronym>DNS</acronym> server
	running <acronym>BIND</acronym> 9.  While all versions of
	<acronym>BIND</acronym> 9 support <acronym>DNSSEC</acronym>, it is
	necessary to have at least version 9.6.2 in order to be able to use the
	signed root zone when validating <acronym>DNS</acronym> queries.  This
	is because earlier versions lack the required algorithms to enable
	validation using the root zone key.  It is strongly recommended to use
	the latest version of <acronym>BIND</acronym> 9.7 or later to take
	advantage of automatic key updating for the root key, as well as other
	features to automatically keep zones signed and signatures up to date.
	Where configurations differ between 9.6.2 and 9.7 and later,
	differences will be pointed out.</para>

      <sect3>
	<title>Recursive <acronym>DNS</acronym> server configuration</title>

	<para>Enabling <acronym>DNSSEC</acronym> validation of queries
	  performed by a recursive <acronym>DNS</acronym> server requires a few

	  role="Key Signing Key">KSK</acronym>).  The second key, with value
	  256, is a subordinate key, commonly called a Zone Signing Key
	  (<acronym role="Zone Signing Key">ZSK</acronym>).  More on the
	  different key types later in <xref linkend="dns-dnssec-auth">.</para>
	  linkend="dns-dnssec-auth">.</para>

	<para>Now the key must be verified and formatted so that
	  <acronym>BIND</acronym> can use it.  To verify the key, generate a

      <title>Security</title>

      <para>Although BIND is the most common implementation of DNS,
	there is always the issue of security.  Possible and
	exploitable security holes are sometimes found.
      </para>

      <para>While &os; automatically drops

      <title>Further Reading</title>

      <para>BIND/<application>named</application> manual pages:
	&man.rndc.8; &man.named.8; &man.named.conf.5; &man.nsupdate.8;
	&man.dnssec-signzone.8; &man.dnssec-keygen.8;</para>

      <itemizedlist>
	<listitem>

	</listitem>

	<listitem>
	  <para><ulink url="http://www.oreilly.com/catalog/dns5/">O'Reilly
	    DNS and BIND 5th Edition</ulink></para>
	</listitem>

	<listitem>

	</listitem>

	<listitem>
	  <para><ulink url="http://tools.ietf.org/html/rfc5011">RFC 5011
	    - Automated Updates of DNS Security (<acronym>DNSSEC</acronym>
	    Trust Anchors</ulink></para>
	</listitem>
      </itemizedlist>
    </sect2>

    </sect1info>
    <title>Apache HTTP Server</title>

    <indexterm>
      <primary>web servers</primary>
      <secondary>setting up</secondary>
    </indexterm>
    <indexterm>
      <primary>Apache</primary>
    </indexterm>

    <sect2>
      <title>Overview</title>

      <para>&os; is used to run some of the busiest web sites in the
	world.  The majority of web servers on the Internet are using
	the <application>Apache HTTP Server</application>.
	<application>Apache</application> software packages should be
	included on your FreeBSD installation media.  If you did not
	install <application>Apache</application> when you first
	installed FreeBSD, then you can install it from the <filename
	role="package">www/apache13</filename> or <filename
	role="package">www/apache22</filename> port.</para>

      <para>Once <application>Apache</application> has been installed
	successfully, it must be configured.</para>

      <note>
	<para>This section covers version 1.3.X of the
	  <application>Apache HTTP Server</application> as that is the
	  most widely used version for &os;.  <application>Apache</application>&nbsp;2.X introduces many
	  new technologies but they are not discussed here.  For more
	  information about <application>Apache</application>&nbsp;2.X, please see <ulink
	  url="http://httpd.apache.org/"></ulink>.</para>
	</note>

    </sect2>

    <sect2>
      <title>Configuration</title>

      <indexterm>
	<primary>Apache</primary>
	<secondary>configuration file</secondary>
      </indexterm>

      <para>The main <application>Apache HTTP Server</application> configuration file is
	installed as

    <sect2>
      <title>Running <application>Apache</application></title>

      <indexterm>
	<primary>Apache</primary>
	<secondary>starting or stopping</secondary>
      </indexterm>

      <para><application>Apache</application> does not run from the
	<application>inetd</application> super server as many other
	network servers do.  It is configured to run standalone for
	better performance for incoming HTTP requests from client web
	browsers.  A shell script wrapper is included to make
	starting, stopping, and restarting the server as simple as
	possible.  To start up <application>Apache</application> for
	the first time, just run:</para>

      <screen>&prompt.root; <userinput>/usr/local/sbin/apachectl start</userinput></screen>


      <screen>&prompt.root; <userinput>/usr/local/sbin/apachectl stop</userinput></screen>

      <para>After making changes to the configuration file for any
	reason, you will need to restart the server:</para>

      <screen>&prompt.root; <userinput>/usr/local/sbin/apachectl restart</userinput></screen>


	&man.apachectl.8; manual page.</para>

      <para>To launch <application>Apache</application> at system
	startup, add the following line to
	<filename>/etc/rc.conf</filename>:</para>

      <programlisting>apache_enable="YES"</programlisting>


      <programlisting>apache_flags=""</programlisting>

      <para>Now that the web server is running, you can view your web
	site by pointing a web browser to
	<literal>http://localhost/</literal>.  The default web page
	that is displayed is
	<filename>/usr/local/www/data/index.html</filename>.</para>

    </sect2>


	different domains to share the same IP address.</para>

      <para>To setup <application>Apache</application> to use
	Name-based Virtual Hosting add an entry like the following to
	your <filename>httpd.conf</filename>:</para>

      <programlisting>NameVirtualHost *</programlisting>

      <para>If your webserver was named <hostid role="fqdn">www.domain.tld</hostid>
	and you wanted to setup a virtual domain for
	<hostid role="fqdn">www.someotherdomain.tld</hostid> then you would add
	the following entries to
	<filename>httpd.conf</filename>:</para>

      <screen>&lt;VirtualHost *&gt;
ServerName www.domain.tld

&lt;/VirtualHost&gt;</screen>

      <para>Replace the addresses with the addresses you want to use
	and the path to the documents with what you are using.</para>

      <para>For more information about setting up virtual hosts,
	please consult the official <application>Apache</application>
	documentation at: <ulink
	url="http://httpd.apache.org/docs/vhosts/"></ulink>.</para>

    </sect2>

    <sect2>
      <title>Apache Modules</title>

      <indexterm>
	<primary>Apache</primary>
	<secondary>modules</secondary>
      </indexterm>

      <para>There are many different <application>Apache</application>
	modules available to add
	functionality to the basic server.  The FreeBSD Ports
	Collection provides an easy way to install
	<application>Apache</application> together with some of the
	more popular add-on modules.</para>

      <sect3>
	<title>mod_ssl</title>

	<indexterm>
	  <primary>web servers</primary>
	  <secondary>secure</secondary>
	</indexterm>
	<indexterm>
	  <primary>SSL</primary>
	</indexterm>
	<indexterm>
	  <primary>cryptography</primary>
	</indexterm>

	<para>The <application>mod_ssl</application> module uses the OpenSSL library to provide
	  strong cryptography via the Secure Sockets Layer (SSL v2/v3)
	  and Transport Layer Security (TLS v1) protocols.  This
	  module provides everything necessary to request a signed
	  certificate from a trusted certificate signing authority so
	  that you can run a secure web server on &os;.</para>

	<para>If you have not yet installed
	  <application>Apache</application>, then a version of <application>Apache</application>

      </sect3>

      <sect3>
	<title>Language Bindings</title>

	<para>There are Apache modules for most major scripting
	  languages.  These modules typically make it possible to
	  write <application>Apache</application> modules entirely in
	  a scripting language.  They are also often used as a
	  persistent interpreter embedded into the server that avoids
	  the overhead of starting an external interpreter and the
	  startup-time penalty for dynamic websites, as described in
	  the next section.</para>
      </sect3>
    </sect2>

    <sect2>
      <title>Dynamic Websites</title>

      <indexterm>
	<primary>web servers</primary>
	<secondary>dynamic</secondary>
      </indexterm>

      <para>In the last decade, more businesses have turned to the
	Internet in order to enhance their revenue and increase
	exposure.  This has also increased the need for interactive
	web content.  While some companies, such as &microsoft;,
	have introduced solutions into their proprietary products,
	the open source community answered the call.  Modern options
	for dynamic web content include Django, Ruby on Rails,
	<application>mod_perl</application>, and
	<application>mod_php</application>.</para>

      <sect3>
	<title>Django</title>

	<indexterm>
	  <primary>Python</primary>
	</indexterm>
	<indexterm>
	  <primary>Django</primary>
	</indexterm>

	<para>Django is a BSD licensed framework designed to allow
	  developers to write high performance, elegant web
	  applications quickly.  It provides an object-relational
	  mapper so that data types are developed as Python objects,
	  and a rich dynamic database-access API is provided for those
	  objects without the developer ever having to write SQL.  It
	  also provides an extensible template system so that the
	  logic of the application is separated from the HTML
	  presentation.</para>

	<para>Django depends on <application>mod_python</application>,
	  <application>Apache</application>, and an SQL database
	  engine of your choice.  The FreeBSD Port will install all of
	  these pre-requisites for you with the appropriate flags.</para>

	<example id="network-www-django-install">
	  <title>Installing Django with Apache2, mod_python3, and PostgreSQL</title>

	  <screen>&prompt.root; <userinput>cd /usr/ports/www/py-django; make all install clean -DWITH_MOD_PYTHON3 -DWITH_POSTGRESQL</userinput></screen>
	</example>

	<para>Once Django and these pre-requisites are installed, you
	  will need to create a Django project directory and then

	<example id="network-www-django-apache-config">
	  <title>Apache Configuration for Django/mod_python</title>

	<para>You will need to add a line to the apache
	  <filename>httpd.conf</filename> file to configure Apache
	  to pass requests for certain URLs to your web
	  application:</para>

	<screen>&lt;Location "/"&gt;
    SetHandler python-program
    PythonPath "['/dir/to/your/django/packages/'] + sys.path"
    PythonHandler django.core.handlers.modpython

      </sect3>

      <sect3>
	<title>Ruby on Rails</title>

	<indexterm>
	  <primary>Ruby on Rails</primary>
	</indexterm>

	<para>Ruby on Rails is another open source web framework that
	  provides a full development stack and is optimized to make

	  powerful applications quickly.  It can be installed easily
	  from the ports system.</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/www/rubygem-rails; make all install clean</userinput></screen>
      </sect3>

      <sect3>
	<title>mod_perl</title>

	<indexterm>
	  <primary>mod_perl</primary>
	  <secondary>Perl</secondary>
	</indexterm>

	<para>The <application>Apache</application>/Perl integration project brings together the
	  full power of the Perl programming language and the <application>Apache
	  HTTP Server</application>.  With the <application>mod_perl</application> module it is possible to
	  write <application>Apache</application> modules entirely in Perl.  In addition, the

	  overhead of starting an external interpreter and the penalty
	  of Perl start-up time.</para>

	<para><application>mod_perl</application> is available a few
	  different ways.  To use <application>mod_perl</application>
	  remember that <application>mod_perl</application> 1.0 only
	  works with <application>Apache</application> 1.3 and
	  <application>mod_perl</application> 2.0 only works with
	  <application>Apache</application> 2.X.
	  <application>mod_perl</application> 1.0 is available in
	  <filename role="package">www/mod_perl</filename> and a
	  statically compiled version is available in
	  <filename role="package">www/apache13-modperl</filename>.
	  <application>mod_perl</application> 2.0 is available in
	  <filename role="package">www/mod_perl2</filename>.</para>
      </sect3>

      <sect3>
	<sect3info>
	  <authorgroup>
	    <author>
	      <firstname>Tom</firstname>

	      <contrib>Written by </contrib>
	    </author>
	  </authorgroup>
	</sect3info>
	<title>mod_php</title>

	<indexterm>
	  <primary>mod_php</primary>
	  <secondary>PHP</secondary>
	</indexterm>

	<para><acronym>PHP</acronym>, also known as <quote>PHP:
	  Hypertext Preprocessor</quote> is a general-purpose scripting
	  language that is especially suited for Web development.
	  Capable of being embedded into <acronym>HTML</acronym> its
	  syntax draws upon C, &java;, and Perl with the intention of
	  allowing web developers to write dynamically generated
	  webpages quickly.</para>

	<para>To gain support for <acronym>PHP</acronym>5 for the
	  <application>Apache</application> web server, begin by

	</note>

	<para>This will install and configure the modules required
	  to support dynamic <acronym>PHP</acronym> applications.  Check
	  to ensure the following sections have been added to
	  <filename>/usr/local/etc/apache/httpd.conf</filename>:</para>

	<programlisting>LoadModule php5_module        libexec/apache/libphp5.so</programlisting>

	<programlisting>AddModule mod_php5.c
    &lt;IfModule mod_php5.c&gt;
        DirectoryIndex index.php index.html
    &lt;/IfModule&gt;

        AddType application/x-httpd-php-source .phps
    &lt;/IfModule&gt;</programlisting>

	<para>Once completed, a simple call to the
	  <command>apachectl</command> command for a graceful
	  restart is needed to load the <acronym>PHP</acronym>
	  module:</para>

	<screen>&prompt.root; <userinput>apachectl graceful</userinput></screen>


	  the selected <literal>OPTIONS</literal> are saved
	  automatically by the &os; Ports framework.</para>

	<para>The <acronym>PHP</acronym> support in &os; is extremely
	   modular so the base install is very limited.  It is very easy
	  to add support using the
	  <filename role="package">lang/php5-extensions</filename> port.
	  This port provides a menu driven interface to
	  <acronym>PHP</acronym> extension installation.
	  Alternatively, individual extensions can be installed using
	  the appropriate port.</para>

	<para>For instance, to add support for the
	  <application>MySQL</application> database server to
	  <acronym>PHP</acronym>5, simply install the port
	  <filename>databases/php5-mysql</filename>.</para>
<!-- deactivate the filename link as there is no pkg-descr file for this port -->
<!-- <filename role="package">databases/php5-mysql</filename> port.</para> -->
	<para>After installing an extension, the
	  <application>Apache</application> server must be reloaded to
	  pick up the new configuration changes:</para>
          <para>After installing an extension, the
            <application>Apache</application> server must be reloaded to
              pick up the new configuration changes:</para>

	<screen>&prompt.root; <userinput>apachectl graceful</userinput></screen>
      </sect3>

    </sect1info>
    <title>File Transfer Protocol (FTP)</title>

    <indexterm>
      <primary>FTP servers</primary>
    </indexterm>

    <sect2>
      <title>Overview</title>

	for anonymous users.</para>

      <para>Once the FTP server has been configured properly, it must
	be enabled in <filename>/etc/inetd.conf</filename>.  All that
	is required here is to remove the comment symbol
	<quote>#</quote> from in front of the existing
	<application>ftpd</application> line :</para>

      <programlisting>ftp	stream	tcp	nowait	root	/usr/libexec/ftpd	ftpd -l</programlisting>

      <para>As explained in <xref linkend="network-inetd-reread">,
	the <application>inetd</application> configuration must be reloaded
	after this configuration file is changed.  Please refer to
	<xref linkend="network-inetd-settings"> for details on enabling
	<application>inetd</application> on your system.</para>


    <sect2>
      <title>Maintaining</title>

      <indexterm>
	<primary>syslog</primary>
      </indexterm>
      <indexterm>
	<primary>log files</primary>
	<secondary>FTP</secondary>
      </indexterm>

      <para>The <application>ftpd</application> daemon uses
	&man.syslog.3; to log messages.  By default, the system log
	daemon will put messages related to FTP in the
	<filename>/var/log/xferlog</filename> file.  The location of
	the FTP log can be modified by changing the following line in
	<filename>/etc/syslog.conf</filename>:</para>

      <programlisting>ftp.info      /var/log/xferlog</programlisting>


      </indexterm>

      <para>Be aware of the potential problems involved with running
	an anonymous FTP server.  In particular, you should think
	twice about allowing anonymous users to upload files.  You may
	find that your FTP site becomes a forum for the trade of
	unlicensed commercial software or worse.  If you do need to
	allow anonymous FTP uploads, then you should set up the
	permissions so that these files can not be read by other
	anonymous users until they have been reviewed.</para>

    </sect2>
  </sect1>

    </sect1info>
    <title>File and Print Services for &microsoft.windows; clients (Samba)</title>

    <indexterm>
      <primary>Samba server</primary>
    </indexterm>
    <indexterm>
      <primary>Microsoft Windows</primary>
    </indexterm>
    <indexterm>
      <primary>file server</primary>
      <secondary>Windows clients</secondary>

      <title>Overview</title>

      <para><application>Samba</application> is a popular open source
	software package that provides file and print services for
	&microsoft.windows; clients.  Such clients can connect to and
	use FreeBSD filespace as if it was a local disk drive, or
	FreeBSD printers as if they were local printers.</para>

      <para><application>Samba</application> software packages should
	be included on your FreeBSD installation media.  If you did
	not install <application>Samba</application> when you first
	installed FreeBSD, then you can install it from the <filename
	role="package">net/samba34</filename> port or package.</para>

<!-- mention LDAP, Active Directory, WinBIND, ACL, Quotas, PAM, .. -->


      <title>Configuration</title>

      <para>A default <application>Samba</application> configuration
	file is installed as
	<filename>/usr/local/share/examples/samba34/smb.conf.default</filename>.
	This file must be copied to
	<filename>/usr/local/etc/smb.conf</filename> and customized
	before <application>Samba</application> can be used.</para>

      <para>The <filename>smb.conf</filename> file contains runtime
	configuration information for
	<application>Samba</application>, such as definitions of the
	printers and <quote>file system shares</quote> that you would
	like to share with &windows; clients.  The
	<application>Samba</application> package includes a web based
	tool called <application>swat</application> which provides a
	simple way of configuring the <filename>smb.conf</filename>
	file.</para>

      <sect3>
	<title>Using the Samba Web Administration Tool (SWAT)</title>

	  used to configure <application>Samba</application>:</para>

	<programlisting>swat   stream  tcp     nowait/400      root    /usr/local/sbin/swat    swat</programlisting>
	<para>As explained in <xref linkend="network-inetd-reread">,
	  the <application>inetd</application> configuration must be reloaded after this configuration
	  file is changed.</para>

	<para>Once <application>swat</application> has been enabled in
	  <filename>inetd.conf</filename>, you can use a browser to


	  <varlistentry>
	    <term><literal>netbios name</literal></term>
	    <indexterm>
	      <primary>NetBIOS</primary>
	    </indexterm>

	    <listitem>
	      <para>This sets the NetBIOS name by which a <application>Samba</application> server


	    <listitem>
	      <para>The two most common options here are
		<literal>security = share</literal> and <literal>security
		= user</literal>.  If your clients use usernames that
		are the same as their usernames on your &os; machine
		then you will want to use user level security.  This
		is the default security policy and it requires clients
		to first log on before they can access shared
		resources.</para>

	      <para>In share level security, client do not need to log
		onto the server with a valid username and password
		before attempting to connect to a shared resource.
		This was the default security model for older versions
		of <application>Samba</application>.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>passdb backend</literal></term>

	    <indexterm>
	      <primary>NIS+</primary>
	    </indexterm>
	    <indexterm>
	      <primary>LDAP</primary>
	    </indexterm>
	    <indexterm>
	      <primary>SQL database</primary>
	    </indexterm>

	    <listitem>
	      <para><application>Samba</application> has several
		different backend authentication models.  You can
		authenticate clients with LDAP, NIS+, a SQL database,
		or a modified password file.  The default
		authentication method is <literal>smbpasswd</literal>,
		and that is all that will be covered here.</para>
	    </listitem>
	  </varlistentry>

	information about using rc scripts.</para>

      <para><application>Samba</application> actually consists of
	three separate daemons.  You should see that both the
	<application>nmbd</application> and <application>smbd</application> daemons
	are started by the <filename>samba</filename> script.  If
	you enabled winbind name resolution services in
	<filename>smb.conf</filename>, then you will also see that
	the <application>winbindd</application> daemon is started.</para>

      <para>You can stop <application>Samba</application> at any time
	by typing :</para>

      <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/samba stop</userinput></screen>

      <para><application>Samba</application> is a complex software
	suite with functionality that allows broad integration with
	&microsoft.windows; networks.  For more information about
	functionality beyond the basic installation described here,
	please see <ulink url="http://www.samba.org"></ulink>.</para>
    </sect2>

  </sect1>

    </sect1info>
    <title>Clock Synchronization with NTP</title>

    <indexterm>
      <primary>NTP</primary>
    </indexterm>

    <sect2>
      <title>Overview</title>


      <sect3>
	<title>Basic Configuration</title>
	<indexterm>
	  <primary>ntpdate</primary>
	</indexterm>

	<para>If you only wish to synchronize your clock when the
	  machine boots up, you can use &man.ntpdate.8;.  This may be

	  server, add the following line to
	  <filename>/etc/ntp.conf</filename>:</para>

	<programlisting>restrict default ignore</programlisting>

	<note>
	  <para>This will also prevent access from your server to

	    &man.ntp.conf.5; manual for more information.</para>
	</note>

	<para>If you only want to allow machines within your own
	  network to synchronize their clocks with your server, but
	  ensure they are not allowed to configure the server or used
	  as peers to synchronize against, add</para>

	<programlisting>restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap</programlisting>

	<para>instead, where <hostid role="ipaddr">192.168.1.0</hostid> is
	  an IP address on your network and <hostid

  <sect1 id="network-syslogd">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Tom</firstname>
	  <surname>Rhodes</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </sect1info>


      </note>

      <para>Once added, all <literal>facility</literal> messages will
	be logged to the file specified previously,
	<filename>/var/log/logclient.log</filename>.</para>

      <para>The server machine must also have the following listing

Return to bug 157337