nfs-utils/README.NFSv4
Neil Brown 92a46a2e34 - nfs upstream version 1.2.5. Lots of bug fixes
and improved support for pNFS.
  Adds nfsdcld daemon on osd_login script.
  Removed some very out-of-date documentation.

OBS-URL: https://build.opensuse.org/package/show/Base:System/nfs-utils?expand=0&rev=73
2012-05-17 07:07:12 +00:00

405 lines
12 KiB
Plaintext

NFSv4 README
Last updated: 17 May 2012
0. Contents:
-----------
1. Overview.
\___ 1.1 Purpose of this document
2. Quick start
3. Idmapd Configuration on both NFS server and client
4. Setting up NFSv4 server and client
\___ 4.1 Configuring Server
| \___ 4.1.1 /etc/exports
| \___ 4.1.2 Coexisting NFSv4 and NFSv3
| \___ 4.1.3 /etc/sysconfig/nfs
\___ 4.2 Starting services on server and client
\___ 4.3 Mounting the remote exported directories from client
5.Setting up kerberized NFSv4 server and client
\___ 5.1 Prerequisites
\___ 5.2 Configuring kerberized NFS server and client
| \___ 5.2.1 Configuring kerberos
| \___ 5.2.2 Create machine credentials
| \___ 5.2.3 Configure /etc/gssapi_mech.conf
| \___ 5.2.4 /etc/exports entries for kerberised server.
\___ 5.3 Starting services on server and client
\___ 5.4 Mounting the remote exported directories
\___ 5.5 A known issue using NFSv4 with kerberos
6.Troubleshooting
\___ 6.1 Checklist to ensure NFSv4 is up and running
\___ 6.2 Checklist to ensure NFSv4 Kerberos is working properly
1. Overview:
------------
The Network File System Version 4 (NFSv4) is a distributed file system
similar to previous versions of NFS in its straightforward design, and
independence of transport protocols and operating systems for file access in a
heterogeneous network. Unlike earlier versions of NFS, the new protocol
integrates file locking, strong security, Compound RPCs (combining relevant
operations), and delegation capabilities to enhance client performance for
narrow data sharing applications on high-bandwidth networks. NFSv4
implementations are backward compatible with NFSv2 and NFSv3.
Note: NFSv4 ACLs and krb5p (Kerberos Privacy) are currently not supported
1.1 The Purpose of this document
________________________________
This document is intended as a step-by-step guide to setup NFSv4 on
openSUSE 12.
It discusses NFSv4 server and client configuration.
2. Quickstart
-------------
For NFSv4 server:
1) /etc/exports does not require any special entries to work with
NFSv4. Earlier SUSE releases required 'fsid=0' on precisely one
entry, and 'bind=' annotations on others. This is no longer required
and should be removed. It is still supported, so there is no need
to change /etc/exports when upgrading to openSUSE 12.
2) Edit /etc/idmapd.conf to modify the default "Domain" to contain your
DNS domain name.
3) Execute the following commands to start idmapd and nfsserver
#/etc/init.d/idmapd start
#/etc/init.d/nfsserver start
For NFSv4 client:
1) Edit /etc/idmapd.conf to modify the default "Domain" to contain your
DNS domain name.
2) Execute the following command to start idmapd.
#/etc/init.d/idmapd start
3) Mount the exported file system using the following command:
#mount -t nfs4 <servername>:/ <mntpath>
Observe that only "/" is given instead of the actual exported path
name.
3. Idmapd Configuration on client and server
--------------------------------------------
idmapd.conf - configuration file for idmapd (idmapping daemon), which does
NFSV4<=>name mapping. Here dns domain (Domain) name has to be configured in
both client and server.
Sample Configuration file:
==========================================================================
[General]
Verbosity = 0
Pipefs-Directory = /var/lib/nfs/rpc_pipefs
Domain = mydomain.com
[Mapping]
Nobody-User = nobody
Nobody-Group = nobody
==========================================================================
4. Setting up NFSv4 server and client
-------------------------------------
4.1 Configuring Server
___________________________
There are three main configuration files you will need to edit to set up an
NFSv4 server:
/etc/sysconfig/nfs and /etc/idmapd.conf.
we will describe the first here as idmapd.conf is done in previous section.
4.1.1 /etc/sysconfig/nfs
=========================
/etc/sysconfig/nfs is another NFS server configuration file. Here the number
of kernel threads, NFSv4 support and GSS security (kerberos) for NFS can be
configured (kerberos set up is explained in Section 5.)
4.2 Starting services on server and client
__________________________________________
We need to start idmapd and nfsserver on the NFSv4 server.
#/etc/init.d/idmapd start
#/etc/init.d/nfsserver start
and start idmapd alone on the client.
If the machines that are being used as client and server are just meant for
that, the daemons can be enabled during bootup as shown below.
Use insserv to do this
#insserv -d idmapd
#insserv -d nfsserver
and idmapd alone on the client.
4.3 Mounting remote exported directories
________________________________________
One main difference between previous versions of NFS and NFSv4 is the way in
which mount is invoked. With regard to the pseudofilesystem concept
sketched above, mount is done as follows:
#mount -t nfs4 <servername>:/ <mntpath>
Observe that only '/' is given after the servername.
5. Setting up kerberized NFSv4 server and client
------------------------------------------------
5.1 Prerequisites
_________________
o Key Distribution Center (KDC) must already be set up on the network.
o krb5-1.4.x must be installed on both NFS server and NFS client.
o krb5-client-1.4.x must be installed on both NFS server and NFS client.
o NFS server, client and the KDC server must have their time synchronized.
o NFS_SECURITY_GSS has to be set to "yes" in /etc/sysconfig/nfs in both
server and client.
5.2 Configuring Kerberized NFSv4 server and client
__________________________________________________
All the following configuration steps except 5.2.4 are for both NFSv4
client and server.
5.2.1 Configure kerberos
========================
Edit krb5.conf.
Sample configuration
==========================================================================
[libdefaults]
default_realm = MYDOMAIN.COM
dns_lookup_realm = true
dns_lookup_kdc = true
[realms]
MYDOMAIN.COM = {
kdc = kdcserver.mydomain.com
admin_server = adminserver.mydomain.com
default_domain = mydomain.com
}
[domain_realm]
mydomain.com = MYDOMAIN.COM
.mydomain.com = MYDOMAIN.COM
[logging]
kdc = FILE:/var/log/krb5kdc.log
admin_server = FILE:/var/log/kadmin.log
default = FILE:/var/log/krb5lib.log
==========================================================================
Replace MYDOMAIN.COM with your REALM, kdcserver.mydomain.com with your KDC
server, adminserver.mydomain.com with your Admin server & mydomain.com with
your DNS domain name.
5.2.2 Create machine credentials
================================
This means creating a Kerberos V5 principal/instance name of the form
nfs/<hostname>@REALM, and either adding a key for this principal to
an existing /etc/krb5.keytab or creating an /etc/krb5.keytab.
Note: only the encryption type of des-cbc-crc is functional so far in the
kernel, so add only this type of key.
kadmin: addprinc -e des-cbc-crc:normal nfs/<hostname>@REALM
kadmin: ktadd -e des-cbc-crc:normal -k /etc/krb5.keytab nfs/<hostname>@REALM
5.2.3 Configure /etc/gssapi_mech.conf
=====================================
This configuration file determines which GSS-API mechanisms the gssd code
should use. Usually no need to modify this file in 32 bit machines because
the libraries are installed in /usr/lib.
Note:
In case of 64 bit machines this has to be modified to /usr/lib64. This is
a workaround and will be fixed later.
Sample configuration
==========================================================================
# GSSAPI Mechanism Definitions
#
# This configuration file determines which GSS-API mechanisms
# the gssd code should use
#
# NOTE:
# The initialization function "mechglue_internal_krb5_init"
# is used for the MIT krb5 gssapi mechanism. This special
# function name indicates that an internal function should
# be used to determine the entry points for the MIT gssapi
# mechanism functions.
#
# library initialization function
# ================================ ==========================
# The MIT K5 gssapi library, use special function for initialization.
/usr/lib/libgssapi_krb5.so mechglue_internal_krb5_init
#
# The SPKM3 gssapi library function. Use the function spkm3_gss_initialize.
# /usr/local/gss_mechs/spkm/spkm3/libgssapi_spkm3.so spkm3_gss_initialize
==========================================================================
5.2.4 /etc/exports entries for a kerberized server
==================================================
Typical entries for kerberos security mode looks like these:
/export gss/krb5(rw,insecure,no_subtree_check,sync,no_root_squash)
/export gss/krb5i(rw,insecure,no_subtree_check,sync,no_root_squash)
Note:
i) option 'insecure' - The insecure option in this entry also allows clients
with NFS implementations that don't use a reserved port for NFS. So it is
advisable *NOT* to use this option unless you have a kerberised set up or
you know what you are doing.
5.3 Starting the services on server and client
______________________________________________
On NFSv4 server, svcgssd needs to be started too. So,
#/etc/init.d/idmapd start
#/etc/init.d/svcgssd start
#/etc/init.d/nfsserver start
On NFSv4 client, gssd needs to be started too. So,
#/etc/init.d/idmapd start
#/etc/init.d/gssd start
Or
To avoid starting manually, enable service during bootup using insserv as
mentioned in 4.2
5.4 Mounting exported directories with kerberos
_______________________________________________
To mount a filesystem using krb5, provide the "-osec=krb5" option to mount.
#mount -tnfs4 -osec=<secmode> nfsserver:/ /mntpoint
<secmode> can be krb5(Autentication) or krb5i (Integrity).
5.5 A known issue using NFSv4 with kerberos
___________________________________________
Even if "no_root_squash" option is used, while exporting a filesystem at the
server, root on the client gets a "Permission denied" error when creating
files on the mount point.
This is because there is no proper mapping between root and the GSSAuthName.
Note: Trying to set 777 permission is not correct as it is not secure. Also,
any file created on the mountpoint will have "nobody" as owner.
There is a work around for this if both NFS server and client use ldap_umich
methods to authenticate. If the idmapd on both server and client is configured
to use ldap_umich modules then having GSSAuthName (<nfs/hostname@realm>)
parameter map to root user, on the ldap server will solve this problem.
A proper fix for this issue is being worked upon.
6. Troubleshooting
-------------------
6.1 Checklist to ensure NFSV4 is up and running
_______________________________________________
1. ps -ef | grep nfsd
ps -ef | grep idmapd
ps -ef | grep svcgssd
to check server side daemons are up and running.
2. ps -ef | grep idmapd
ps -ef | grep gssd
to check client side daemons are up and running
3. rpcinfo -p
to check all registered RPC programs (nfs, portmapper, mountd) & versions
4. Check firewall is enabled on server/client from YAST.
Yast -> Security and Users -> Firewall.
Make sure NFS service is enabled.
5. showmount -e <server name>
to check mount information on NFS server
6. If users are not mapped properly check whether idmapd is running in both
server & client and dns domain name is properly configured.
7. If you unable to mount, check for the correctness of the exports file entry.
6.2 Check list to ensure kerberos is working properly
_____________________________________________________
There are many reasons this could be failing.
1. Verify that rpc.gssd is running on the client and rpc.svcgssd is running
on the server.
2. Verify that your hostnames are correct. The hostname command should return
a fully-qualified hostname that has a correct DNS reverse-mapping (either
through DNS or the /etc/hosts file).
3. Verify there is a keytab entry for nfs/<hostname>@REALM in your keytab file
(/etc/krb5.keytab).
4. Verify your Kerberos configuration file has the proper mapping from the DNS
hostname to the correct realm. The [domain_realm] section of the
/etc/krb5.conf needs to have a mapping from the DNS domain to the correct
REALM.
For example, if your nfs server's hostname is 'foo.abc.org' and your Kerberos
realm name is 'ALPHABET.ORG', then you need an entry like the following in
/etc/krb5.conf on the nfs client machine:
[domain_realm]
.abc.org = ALPHABET.ORG
5. Verify whether your ticket is not expired or not on the client using klist. If
it is expired renew using kinit. This must be checked when you find
"I/O Error" or "Permission denied" while doing file operations.