diff --git a/README.NFSv4 b/README.NFSv4 new file mode 100644 index 0000000..3bf6ee3 --- /dev/null +++ b/README.NFSv4 @@ -0,0 +1,488 @@ +NFSv4 README +Last updated: 15 June 2006 + +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 new 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 SLES 10. +It discusses NFSv4 server and client configuration. + + +2. Quickstart +------------- + +For NFSv4 server: + +1) Edit /etc/exports to have an entry similar to the one below: + + /export (rw,fsid=0,sync,no_root_squash) + + (i) fsid=0 is a must. + (ii) Replace "/export" with file tree that needs to be nfs-exported and + the with client's ip or hostname or *. + (* means any client) + +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 :/ + 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/exports, /etc/sysconfig/nfs and /etc/idmapd.conf. +we will describe the first two here as idmapd.conf is done in previous section. + + +4.1.1 /etc/exports +================== + +This file contains a list of entries; each entry indicates a volume that is +shared and how it is shared. The /etc/exports file format is slightly +different from previous versions. A sample exports entry looks like this. + +/export *(rw,fsid=0,no_subtree_check,sync,no_root_squash) + +Note that: + +i) fsid - The value 0 has a special meaning when use with NFSv4. NFSv4 has a + concept of a root of the overall exported filesystem. The export point + exported with fsid=0 will be used as this root. + There must be at least one entry with fsid=0. (this will be pseudo file + system's /) + +ii) The method used to mount multiple exported trees is different. NFSv4 uses + the concept of pseudo filesystem to give a single file system view to the + client with a pseudo-"/" as root of the filesystem tree. To illustrate, + + Suppose we have + + /path1/volume1 + /path2/volume2 + + as two filesystem trees on the server that need to be exported, then + Firstly, these need to be bound to another name under /export directory + using mount command's bind option. This is done as : + mount --bind /export/ + i.e. in our example: + + #mount --bind /path1/volume1 /export/volume1 + #mount --bind /path2/volume2 /export/volume2 + + will bind these local filesystem trees to their local new names. + Then these two exported filesystems (with their newly bound paths) are + entered into /etc/exports with their respective independent options. + i.e. /etc/exports would contain - + + /export/volume1 *() + /export/volume2 *() + +iii)If both a directory and its subdirectory residing on different file systems + need to be exported, then the option 'nohide' must be appropriately used. + /export and /export/subdir are on differnt file systems + and both need to be exported to same client then + + /export () + /export/subdir (,nohide) + + must be done so that the client can see the contents of subdir too. + Though this is not specific to NFSv4, it is seen as a common use case + scenario and is included here. + 'man exports' has more info. + +iv) Currently Yast2's nfs-server module can only be used as a subsitute + for manually editing the /etc/exports. Fully functional yast with other + configuration editing (idmapd etc) is work in progress. + +v) In case of different kind of exports for the same exported path the + syntax that must be followed is either of the following + /export host1() host2() + (or) + /export host1() + /export host2() + + + +4.1.2 Co-existing NFSv3 and NFSv4 exports for same file systems +=============================================================== + +NFSv4 current linux implementation caters to serving NFSv2 and NFSv3 clients +too. The /etc/exports can contain both type of export entries even for the +same filesystem trees being exported. + + +4.1.3 /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 :/ + + 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/@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/@REALM +kadmin: ktadd -e des-cbc-crc:normal -k /etc/krb5.keytab nfs/@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,fsid=0,insecure,no_subtree_check,sync,no_root_squash) +/export gss/krb5i(rw,fsid=0,insecure,no_subtree_check,sync,no_root_squash) + +Note: +i) krb5p (Privacy) is currently not supported. + +ii) 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= nfsserver:/ /mntpoint + + 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 () +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 + to check mount information on NFS server + +6. Make sure that one and only one path is exported + with fsid=0. + Refer Pseudofilesystems (point (iii) in Section 3.2.1) for more information. + +7. If users are not mapped properly check whether idmapd is running in both + server & client and dns domain name is properly configured. + +8. 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/@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. + diff --git a/nfs-utils.changes b/nfs-utils.changes index aec58a2..1350bfa 100644 --- a/nfs-utils.changes +++ b/nfs-utils.changes @@ -1,3 +1,8 @@ +------------------------------------------------------------------- +Thu Jul 19 16:40:38 CEST 2007 - ro@suse.de + +- added README.NFSv4 (#182775) + ------------------------------------------------------------------- Tue Jul 17 13:32:25 CEST 2007 - meissner@suse.de diff --git a/nfs-utils.spec b/nfs-utils.spec index bc260c0..5dc0e70 100644 --- a/nfs-utils.spec +++ b/nfs-utils.spec @@ -15,7 +15,7 @@ BuildRequires: e2fsprogs-devel gcc-c++ krb5-devel libevent librpcsecgss nfsidma URL: http://nfs.sourceforge.net Summary: Support Utilities for Kernel nfsd Version: 1.1.0 -Release: 4 +Release: 5 Group: Productivity/Networking/NFS License: GPL v2 or later BuildRoot: %{_tmppath}/%{name}-%{version}-build @@ -28,6 +28,7 @@ Source2: nfs.init Source3: nfsserver.init Source4: sysconfig.nfs-nfs-utils Source5: nfs-kernel-server.xml +Source6: README.NFSv4 Patch0: nfs-utils-largefiles.patch Patch1: nfs-utils-1.0.7-bind-syntax.patch @@ -102,6 +103,7 @@ Authors: %setup -q -n nfs-utils-%{version} -a 1 %patch0 -p1 %patch1 -p1 +cp %{S:6} . %build %{?suse_update_config:%{suse_update_config -f }} @@ -228,9 +230,11 @@ rm -rf $RPM_BUILD_ROOT %files -n nfs-doc %defattr(-,root,root) -%doc nfs/*.html nfs/*.ps linux-nfs/* +%doc nfs/*.html nfs/*.ps linux-nfs/* README.NFSv4 %changelog +* Thu Jul 19 2007 - ro@suse.de +- added README.NFSv4 (#182775) * Tue Jul 17 2007 - meissner@suse.de - buildrequire nfsidmap-devel * Fri Jun 22 2007 - ro@suse.de