From owner-svn-doc-head@FreeBSD.ORG Tue Oct 15 18:39:12 2013 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id 9EE4AB52; Tue, 15 Oct 2013 18:39:12 +0000 (UTC) (envelope-from dru@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 7E9D42E7C; Tue, 15 Oct 2013 18:39:12 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r9FIdCsw020799; Tue, 15 Oct 2013 18:39:12 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r9FIdCBu020798; Tue, 15 Oct 2013 18:39:12 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201310151839.r9FIdCBu020798@svn.freebsd.org> From: Dru Lavigne Date: Tue, 15 Oct 2013 18:39:12 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42968 - head/en_US.ISO8859-1/books/handbook/network-servers X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 15 Oct 2013 18:39:12 -0000 Author: dru Date: Tue Oct 15 18:39:12 2013 New Revision: 42968 URL: http://svnweb.freebsd.org/changeset/doc/42968 Log: Another dent in this very large chapter. This patch does the following: - fixes &os; and most instances of "you" - fixes manual page repitition - some word-smithing - some heading tightening in the NIS section - some clarification in the NIS server section Modified: head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Tue Oct 15 16:57:03 2013 (r42967) +++ head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Tue Oct 15 18:39:12 2013 (r42968) @@ -156,7 +156,7 @@ auth, and daytime. - This section will cover the basics in configuring + This section covers the basics in configuring inetd through its command-line options and its configuration file, /etc/inetd.conf. @@ -191,7 +191,7 @@ Like most server daemons, inetd has a number of options that it can be passed in order to - modify its behaviour. See the &man.inetd.8; manual page for + modify its behaviour. Refer to &man.inetd.8; for the full list of options. Options can be passed to inetd @@ -207,8 +207,8 @@ users may be pleased to note that these parameters usually do not need to be modified. These options may be useful if an excessive amount of connections are being established. - A full list of options can be found in the - &man.inetd.8; manual. + A full list of options can be found in + &man.inetd.8;. @@ -264,7 +264,7 @@ <filename>inetd.conf</filename> Configuration of inetd is - done via the file /etc/inetd.conf. + done by editing /etc/inetd.conf. When a modification is made to /etc/inetd.conf, @@ -515,8 +515,8 @@ server-program-argumentsmax-child-per-ip can be used to limit such attacks. - By default, TCP wrapping is turned on. Consult the - &man.hosts.access.5; manual page for more information on + By default, TCP wrapping is turned on. Consult + &man.hosts.access.5; for more information on placing TCP restrictions on various inetd invoked daemons. @@ -536,7 +536,7 @@ server-program-arguments - Consult the &man.inetd.8; manual page for more in-depth + Consult &man.inetd.8; for more in-depth information. @@ -592,8 +592,7 @@ server-program-arguments - Removable media storage devices, such as floppy disks - or CD-ROM drives, can be used by other + Removable media storage devices can be used by other machines on the network. This reduces the number of devices throughout the network and provides a centralized location to manage their security. @@ -840,7 +839,7 @@ mountd_flags="-r" server:/home /mnt nfs rw 0 0 - The &man.fstab.5; manual page lists all the available + Refer to &man.fstab.5; for a description of all available options. @@ -870,7 +869,7 @@ rpc_statd_enable="YES" If locking is not required on the server, the NFS client can be configured to lock locally by passing to &man.mount.nfs.8;. - Refer to the &man.mount.nfs.8; manual page for further + Refer to &man.mount.nfs.8; for further details. @@ -1009,7 +1008,7 @@ Exports list on foobar: /etc/amd.conf defines some of the more advanced features of amd. - Consult the &man.amd.8; and &man.amd.conf.5; manual pages + Consult &man.amd.8; and &man.amd.conf.5; for more information. @@ -1037,7 +1036,7 @@ Exports list on foobar: --> - Network Information System (NIS/YP) + Network Information System (<acronym>NIS</acronym>) NIS Solaris @@ -1071,7 +1070,7 @@ Exports list on foobar: domain to share a common set of configuration files. This permits a system administrator to set up NIS client systems with only minimal - configuration data and add, remove or modify configuration + configuration data and to add, remove, or modify configuration data from a single location. @@ -1105,9 +1104,9 @@ Exports list on foobar: NIS domain name - An NIS master server and all - of its clients, including its slave servers, share a - NIS domain name which does not have + NIS servers and + clients share an + NIS domain name. Typically, this name does not have anything to do with DNS. @@ -1192,7 +1191,7 @@ Exports list on foobar: clients are stored on the master server. While it is possible for one machine to be an NIS master server for more than one NIS - domain, this will not be covered in chapter as it + domain, this type of configuration will not be covered in this chapter as it assumes a relatively small-scale NIS environment. @@ -1233,13 +1232,13 @@ Exports list on foobar: Planning Considerations This section describes a sample NIS - environment which consists of 15 &os; machines and which - currently has no centralized point of administration. Each + environment which consists of 15 &os; machines with + no centralized point of administration. Each machine has its own /etc/passwd and /etc/master.passwd. These files are kept in sync with each other only through manual intervention. Currently, when a user is added to the lab, - the process must be repeated on all 15 machines.. + the process must be repeated on all 15 machines. The configuration of the lab will be as follows: @@ -1288,7 +1287,7 @@ Exports list on foobar: - If this is the first time a NIS + If this is the first time an NIS scheme is being developed, it should be thoroughly planned ahead of time. Regardless of network size, several decisions need to be made as part of the planning @@ -1346,14 +1345,14 @@ Exports list on foobar: - Configuring the <acronym>NIS</acronym> Servers + Configuring the <acronym>NIS</acronym> Master Server The canonical copies of all NIS files are stored on the master server. The databases used to store the information are called NIS maps. In &os;, these maps are stored in - /var/yp/[domain name] where - [domain name] is the name of the + /var/yp/[domainname] where + [domainname] is the name of the NIS domain. Since multiple domains are supported, it is possible to have several directories, one for each domain. Each domain will have its own independent @@ -1367,10 +1366,6 @@ Exports list on foobar: database file, and transmitting data from the database back to the client. - - Setting Up a <acronym>NIS</acronym> Master - Server - NIS server configuration @@ -1408,11 +1403,25 @@ Exports list on foobar: - Depending on the NIS setup, - additional entries may be required. Refer to if the - NIS server is also an - NIS clients. + Care must be taken + in a multi-server domain + where the server machines are also NIS + clients. It is generally a good idea to force the servers to + bind to themselves rather than allowing them to broadcast bind + requests and possibly become bound to each other. Strange + failure modes can result if one server goes down and others + are dependent upon it. Eventually, all the clients will time + out and attempt to bind to other servers, but the delay + involved can be considerable and the failure mode is still + present since the servers might bind to each other all over + again. + + A server that is also a client can be forced to bind to a particular server by + adding these additional lines to + /etc/rc.conf: + + nis_client_enable="YES" # run client stuff as well +nis_client_flags="-S NIS domain,server" After saving the edits, type /etc/netstart to restart the network @@ -1422,7 +1431,6 @@ Exports list on foobar: &man.ypserv.8;: &prompt.root; service ypserv start - Initializing the <acronym>NIS</acronym> @@ -1432,13 +1440,12 @@ Exports list on foobar: <primary>NIS</primary> <secondary>maps</secondary> </indexterm> - <para><acronym>NIS</acronym> maps are database files stored - in <filename class="directory">/var/yp</filename>. They - are generated from configuration files in <filename + <para><acronym>NIS</acronym> maps + are generated from the configuration files in <filename class="directory">/etc</filename> on the <acronym>NIS</acronym> master, with one exception: <filename>/etc/master.passwd</filename>. This is to - prevent the propagation passwords to all the servers in + prevent the propagation of passwords to all the servers in the <acronym>NIS</acronym> domain. Therefore, before the <acronym>NIS</acronym> maps are initialized, configure the primary password files:</para> @@ -1457,7 +1464,7 @@ Exports list on foobar: group or world readable by setting its permissions to <literal>600</literal>.</para></note> - <para>When this task has been completed, it is time to + <para>After completing this task, initialize the <acronym>NIS</acronym> maps. &os; includes the &man.ypinit.8; script to do this. When generating maps for the master server, include @@ -1488,25 +1495,21 @@ Is this correct? [y/n: y] <userinput>y< NIS Map update completed. ellington has been setup as an YP master server without any errors.</screen> - <para>At this point, <command>ypinit</command> should have - created <filename>/var/yp/Makefile</filename> from - <filename>/var/yp/Makefile.dist</filename>. When created, - this file assumes that the operating environment is a - single server <acronym>NIS</acronym> system with only &os; - machines. Since <literal>test-domain</literal> has a - slave server as well, edit - <filename>/var/yp/Makefile</filename> as well:</para> - - <screen>ellington&prompt.root; <userinput>vi /var/yp/Makefile</userinput></screen> - - <para>You should comment out the line that says</para> + <para>This will + create <filename>/var/yp/Makefile</filename> from + <filename>/var/yp/Makefile.dist</filename>. By default, + this file assumes that the environment has a + single <acronym>NIS</acronym> server with only &os; + clients. Since <literal>test-domain</literal> has a + slave server, edit this line in + <filename>/var/yp/Makefile</filename> so that it begins with a + comment (<literal>#</literal>):</para> <programlisting>NOPUSH = "True"</programlisting> - - <para>(if it is not commented out already).</para> </sect3> + </sect2> - <sect3> + <sect2> <title>Setting up a <acronym>NIS</acronym> Slave Server @@ -1515,15 +1518,14 @@ ellington has been setup as an YP master slave server 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 - /etc/rc.conf as you did before. The - only difference is that we now must use the - option when running - ypinit. The option - requires the name of the NIS master be - passed to it as well, so our command line looks - like: + simpler than setting up the master. Log on to + the slave server and edit + /etc/rc.conf as before. This + time, include + when running + ypinit. This option + requires the name of the NIS master, as + seen in this example: coltrane&prompt.root; ypinit -s ellington test-domain @@ -1605,9 +1607,9 @@ Remember to update map ypservers on elli Now, run the command /etc/netstart on the slave server as well, which again starts the NIS server. - + - + Setting Up a <acronym>NIS</acronym> Client An NIS client establishes what is @@ -1639,7 +1641,7 @@ Remember to update map ypservers on elli client configuration - Setting up a FreeBSD machine to be a + Setting up a &os; machine to be a NIS client is fairly straightforward. @@ -1708,7 +1710,6 @@ nis_client_enable="YES" After completing these steps, the command, ypcat passwd, should show the server's passwd map. - @@ -2350,35 +2351,6 @@ TWO (,hotel,test-domain) servers still in use today. - - <acronym>NIS</acronym> Servers That Are Also - <acronym>NIS</acronym> Clients - - Care must be taken when running - ypserv in a multi-server domain - where the server machines are also NIS - clients. It is generally a good idea to force the servers to - bind to themselves rather than allowing them to broadcast bind - requests and possibly become bound to each other. Strange - failure modes can result if one server goes down and others - are dependent upon it. Eventually all the clients will time - out and attempt to bind to other servers, but the delay - involved can be considerable and the failure mode is still - present since the servers might bind to each other all over - again. - - A host may be forced to bind to a particular server by - running ypbind with the - flag. Add the following lines to - /etc/rc.conf to enable this feature - during every system boot: - - nis_client_enable="YES" # run client stuff as well -nis_client_flags="-S NIS domain,server" - - See &man.ypbind.8; for further information. - - Password Formats @@ -2663,9 +2635,9 @@ TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv3There will be a prompt for entering the password and, if the process does not fail, a password hash will be added - to the end of slapd.conf. The + to the end of slapd.conf. slappasswd understands several hashing - formats, refer to the manual page for more information. + formats, refer to its manual page for more information. Edit /usr/local/etc/openldap/slapd.conf and @@ -2831,7 +2803,7 @@ result: 0 Success 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 dhclient + network. &os; uses the OpenBSD dhclient taken from OpenBSD 3.7. All information here regarding dhclient is for use with either of the ISC or OpenBSD DHCP clients. The DHCP server is the one included @@ -2840,12 +2812,12 @@ result: 0 Success 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, - dhclient, comes integrated within FreeBSD, + dhclient, comes integrated within &os;, and the server-side portion is available from the net/isc-dhcp42-server port. The + role="package">net/isc-dhcp42-server port. Refer to &man.dhclient.8;, &man.dhcp-options.5;, and - &man.dhclient.conf.5; manual pages, in addition to the - references below, are useful resources. + &man.dhclient.conf.5;, in addition to the + references below, for more information. How It Works @@ -2869,7 +2841,7 @@ result: 0 Success - FreeBSD Integration + &os; Integration &os; fully integrates the OpenBSD DHCP client, dhclient. DHCP client support is provided @@ -2998,24 +2970,23 @@ dhclient_flags="" dhclient requires a configuration file, /etc/dhclient.conf. Typically the file contains only comments, the defaults being - reasonably sane. This configuration file is described by - the &man.dhclient.conf.5; manual page. + reasonably sane. This configuration file is described in + &man.dhclient.conf.5;. /sbin/dhclient - dhclient is statically linked and - resides in /sbin. The - &man.dhclient.8; manual page gives more information about - dhclient. + More information + about + dhclient can be found in &man.dhclient.8;. /sbin/dhclient-script dhclient-script is the - FreeBSD-specific DHCP client configuration script. It + &os;-specific DHCP client configuration script. It is described in &man.dhclient-script.8;, but should not need any user modification to function properly. @@ -3047,7 +3018,7 @@ dhclient_flags="" What This Section Covers This section provides information on how to configure a - FreeBSD system to act as a DHCP server using the ISC + &os; system to act as a DHCP server using the ISC (Internet Systems Consortium) implementation of the DHCP server. @@ -3235,10 +3206,9 @@ dhcpd_ifaces="dc0" dhcpd is statically linked and resides in - /usr/local/sbin. The &man.dhcpd.8; - manual page installed with the port gives more + /usr/local/sbin. More information about - dhcpd. + dhcpd can be found in &man.dhcpd.8;. @@ -3251,8 +3221,8 @@ dhcpd_ifaces="dc0" needs to contain all the information that should be provided to clients that are being serviced, along with information regarding the operation of the server. This - configuration file is described by the - &man.dhcpd.conf.5; manual page installed by the + configuration file is described in + &man.dhcpd.conf.5;, which is installed by the port. @@ -3260,9 +3230,9 @@ dhcpd_ifaces="dc0" /var/db/dhcpd.leases 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. + issued in this file, which is written as a log. The port installs + &man.dhcpd.leases.5;, which + gives a slightly longer description. @@ -3274,8 +3244,8 @@ dhcpd_ifaces="dc0" separate network. If this functionality is required, then install the net/isc-dhcp42-relay - port. The &man.dhcrelay.8; manual page provided with - the port contains more detail. + port. The port installs &man.dhcrelay.8;, which provides + more detail. @@ -3592,13 +3562,13 @@ dhcpd_ifaces="dc0" named_enable="YES" - There are obviously many configuration options for + There are many configuration options for /etc/namedb/named.conf that are beyond - the scope of this document. There are other startup options - for named on &os;, take a look at + the scope of this document. Other startup options + for named on &os; can be found in the named_* - flags in /etc/defaults/rc.conf and - consult the &man.rc.conf.5; manual page. The + flags in /etc/defaults/rc.conf and in + &man.rc.conf.5;. The section is also a good read. @@ -4931,7 +4901,7 @@ DocumentRoot /www/someotherdomain.tld There are many different Apache modules available to add functionality to the basic server. - The FreeBSD Ports Collection provides an easy way to install + The &os; Ports Collection provides an easy way to install Apache together with some of the more popular add-on modules. @@ -5220,7 +5190,7 @@ DocumentRoot /www/someotherdomain.tld software, ftpd, in the base system. This makes setting up and administering an FTP server on - FreeBSD very straightforward. + &os; very straightforward. Configuration @@ -5239,9 +5209,8 @@ DocumentRoot /www/someotherdomain.tld of some users without preventing them completely from using FTP. This can be accomplished with the /etc/ftpchroot file. This file lists - users and groups subject to FTP access restrictions. The - &man.ftpchroot.5; manual page has all of the details so it - will not be described in detail here. + users and groups subject to FTP access restrictions. Refer to + &man.ftpchroot.5; for more details. FTP @@ -5297,7 +5266,7 @@ DocumentRoot /www/someotherdomain.tld &prompt.root; service ftpd start - You can now log on to the FTP server by typing: + Log on to the FTP server by typing: &prompt.user; ftp localhost @@ -5772,8 +5741,8 @@ driftfile /var/db/ntp.driftThis will also prevent access from the server to any servers listed in the local configuration. If there is a need to synchronise the NTP server with an external NTP - server, allow only that specific server. See the - &man.ntp.conf.5; manual for more information. + server, allow only that specific server. Refer to + &man.ntp.conf.5; for more information. To allow machines within the network to synchronize @@ -5937,8 +5906,8 @@ driftfile /var/db/ntp.drift More information on various supported and available - facilities may be found in the - &man.syslog.conf.5; manual page. + facilities may be found in + &man.syslog.conf.5;. Once added, all facility messages will @@ -5962,8 +5931,8 @@ syslogd_flags="-a logclient.example.com Multiple options may be specified to allow logging from multiple clients. IP - addresses and whole netblocks may also be specified, see the - &man.syslog.3; manual page for a full list of possible + addresses and whole netblocks may also be specified. Refer to + &man.syslog.3; for a full list of possible options. Finally, the log file should be created. The method used @@ -6037,8 +6006,8 @@ syslogd_flags="-s -v -v"warning and - info. Please refer to the &man.syslog.3; - manual page for a full list of available facilities and + info. Refer to &man.syslog.3; + for a full list of available facilities and priorities. The logging server must be defined in the client's @@ -6350,9 +6319,9 @@ target iqn.2012-06.com.example:target0 { The current iSCSI initiator is supported starting with &os; 10.0-RELEASE. To use iSCSI initiator available in - older versions, refer to the iscontrol(8) - manual page. This chapter only applies to the new + older versions, refer to iscontrol(8). + This chapter only applies to the new initiator. @@ -6393,8 +6362,8 @@ target iqn.2012-06.com.example:target0 { iqn.2012-06.com.example:target0 10.10.10.10 Connected: da0 This means the iSCSI session was successfully - established, and you have /dev/da0 - representing the attached LUN. Should the target + established, where /dev/da0 + represents the attached LUN. Should the target ("iqn.2012-06.com.example:target0") export more than one LUN, there will be multiple device nodes in the iscictl(8) @@ -6452,7 +6421,7 @@ iqn.2012-06.com.example:target0 The first line ("t0") specifies a nickname for the configuration file section, used at the initiator side to - specify which configuration you want to use. The following + specify which configuration to use. The following lines specify various parameters used during connection - target address and name are mandatory; others are optional; in this case they specify CHAP username and