From patchwork Fri Dec 2 03:58:30 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: NeilBrown X-Patchwork-Id: 9457777 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 7C2F26074E for ; Fri, 2 Dec 2016 04:00:20 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 7197B28489 for ; Fri, 2 Dec 2016 04:00:20 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 6640128505; Fri, 2 Dec 2016 04:00:20 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id CC28628489 for ; Fri, 2 Dec 2016 04:00:19 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753463AbcLBEAT (ORCPT ); Thu, 1 Dec 2016 23:00:19 -0500 Received: from mx2.suse.de ([195.135.220.15]:36611 "EHLO mx2.suse.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753253AbcLBEAS (ORCPT ); Thu, 1 Dec 2016 23:00:18 -0500 X-Virus-Scanned: by amavisd-new at test-mx.suse.de Received: from relay2.suse.de (charybdis-ext.suse.de [195.135.220.254]) by mx2.suse.de (Postfix) with ESMTP id D8693AAA3; Fri, 2 Dec 2016 04:00:16 +0000 (UTC) From: NeilBrown To: "J. Bruce Fields" , Steve Dickson Date: Fri, 02 Dec 2016 14:58:30 +1100 Subject: [PATCH 15/15] Add nfs.systemd man page Cc: linux-nfs@vger.kernel.org Message-ID: <148065111043.28046.3858869219236614683.stgit@noble> In-Reply-To: <148065078775.28046.5506130555300891075.stgit@noble> References: <148065078775.28046.5506130555300891075.stgit@noble> User-Agent: StGit/0.17.1-dirty MIME-Version: 1.0 Sender: linux-nfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-nfs@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP This discusses some of the behaviors of the various unit files, and how best to work with them to achieve various results. Signed-off-by: NeilBrown --- systemd/Makefile.am | 4 + systemd/nfs.systemd.man | 167 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 169 insertions(+), 2 deletions(-) create mode 100644 systemd/nfs.systemd.man -- To unsubscribe from this list: send the line "unsubscribe linux-nfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html diff --git a/systemd/Makefile.am b/systemd/Makefile.am index b5ab157d728b..0d15b9f25ff8 100644 --- a/systemd/Makefile.am +++ b/systemd/Makefile.am @@ -36,8 +36,8 @@ endif endif man5_MANS = nfs.conf.man - -EXTRA_DIST = $(unit_files) $(man5_MANS) +man7_MANS = nfs.systemd.man +EXTRA_DIST = $(unit_files) $(man5_MANS) $(man7_MANS) unit_dir = /usr/lib/systemd/system generator_dir = /usr/lib/systemd/system-generators diff --git a/systemd/nfs.systemd.man b/systemd/nfs.systemd.man new file mode 100644 index 000000000000..01801ebb5f2c --- /dev/null +++ b/systemd/nfs.systemd.man @@ -0,0 +1,167 @@ +.TH NFS.SYSTEMD 7 +.SH NAME +nfs.systemd \- managing NFS services through systemd. +.SH SYNOPSIS +nfs-utils.service +.br +nfs-server.service +.br +nfs-client.target +.br +.I etc +.SH DESCRIPTION +The +.I nfs-utils +package provides a suite of +.I systemd +unit files which allow the various services to be started and +managed. These unit files ensure that the services are started in the +correct order, and the prerequisites are active before dependant +services start. As there are quite few unit files, it is not +immediately obvious how best to achieve certain results. The +following subsections attempt to cover the issues that are most likely +to come up. +.SS Configuration +The standard systemd unit files do not provide any easy way to pass +any command line arguments to daemons so as to configure their +behavior. In many case such configuration can be performed by making +changes to +.I /etc/nfs.conf +or other configuration files. When that is not convenient, a +distribution might provide systemd "drop-in" files which replace the +.B ExecStart= +setting to start the program with different arguments. For example a +drop-in file +.B systemd/system/nfs-mountd.service.d/local.conf +containing +.RS +.nf +[Service] +EnvironmentFile=/etc/sysconfig/nfs +ExecStart= +ExecStart= /usr/sbin/rpc.mountd $RPCMOUNTDOPTS +.fi +.RE +would cause the +.B nfs-mountd.service +unit to run the +.I rpc.mountd +program using, for arguments, the value given for +.B RPCMOUNTDOPTS +in +.IR /etc/sysconfig/nfs . +This allows for seamless integration with existing configuration +tools. +.SS Enabling unit files +There are three unit files which are designed to be manually enabled. +All others are automatically run as required. The three are: +.TP +.B nfs-client.target +This should be enabled on any host which ever serves as an NFS client. +There is little cost in transparently enabling it whenever NFS client +software is installed. +.TP +.B nfs-server.service +This must be enabled to provide NFS service to clients. It starts and +configures the required daemons in the required order. +.TP +.B nfs-blkmap.service +The +.B blkmapd +daemon is only required on NFS clients which are using pNFS (parallel +NFS), and particularly using the +.B blocklayout +layout protocol. If you might use this particular extension to NFS, +the +.B nfs-blkmap.service +unit should be enabled. +.PP +Several other units which might be considered to be optional, such as +.I rpc-gssd.service +are careful to only start if the required configuration file exists. +.I rpc-gsdd.service +will not start if the +.I krb5.keytab +file does not exist (typically in +.IR /etc ). +.SS Restarting NFS services +Most NFS daemons can be restarted at any time. They will reload any +state that they need, and continue servicing requests. This is rarely +necessary though. +.PP +When configuration changesare make, it can be hard to know exactly +which services need to be restarted to ensure that the configuration +takes effect. The simplest approach, which is often the best, is to +restart everything. To help with this, the +.B nfs-utils.service +unit is provided. It declares appropriate dependencies with other +unit files so that +.RS +.B systemctl restart nfs-utils +.RE +will restart all NFS daemons that are running. This will cause all +configuration changes to take effect +.I except +for changes to mount options lists in +.I /etc/fstab +or +.IR /etc/nfsmount.conf . +Mount options can only be changed by unmounting and remounting +filesystem. This can be a disruptive operation so it should only be +done when the value justifies the cost. The command +.RS +.B umount -a -t nfs; mount -a -t nfs +.RE +should unmount and remount all NFS filesystems. +.SS Masking unwanted services +Rarely there may be a desire to prohibit some services from running +even though there are normally part of a working NFS system. This may +be needed to reduce system load to an absolute minimum, or to reduce +attack surface by not running daemons that are not absolutely +required. +.PP +Two particular services which this can apply to are +.I rpcbind +and +.IR idmapd . +.I rpcbind +is not part of the +.I nfs-utils +package, but it used by several NFS services. However it is +.B not +needed when only NFSv4 is in use. If a site will never use NFSv3 (or +NFSv2) and does not want +.I rpcbind +to be running, the correct approach is to run +.RS +.B systemctl mask rpcbind +.RE +This will disable +.IR rpcbind , +and the various NFS services which depend on it (and are only needed +for NFSv3) will refuse to start, without interfering with the +operation of NFSv4 services. In particular, +.I rpc.statd +will not run when +.I rpcbind +is masked. +.PP +.I idmapd +is only needed for NFSv4, and even then is not needed when the client +and server agree to use user-ids rather than user-names to identify the +owners of files. If +.I idmapd +is not needed and not wanted, it can be masked with +.RS +.B systemctl mask idmapd +.RE +.SH FILES +/etc/nfs.conf +.br +/etc/nfsmount.conf +.br +/etc/idmapd.conf +.SH SEE ALSO +.BR systemd.unit (5), +.BR nfs.conf (5), +.BR nfsmount.conf (5).