src/ceph/doc/radosgw/nfs.rst

   1 ===
   2 NFS
   3 ===
   4
   5 .. versionadded:: Jewel
   6
   7 Ceph Object Gateway namespaces can now be exported over file-based
   8 access protocols such as NFSv3 and NFSv4, alongside traditional HTTP access
   9 protocols (S3 and Swift).
  10
  11 In particular, the Ceph Object Gateway can now be configured to
  12 provide file-based access when embedded in the NFS-Ganesha NFS server.
  13
  14 librgw
  15 ======
  16
  17 The librgw.so shared library (Unix) provides a loadable interface to
  18 Ceph Object Gateway services, and instantiates a full Ceph Object Gateway
  19 instance on initialization.
  20
  21 In turn, librgw.so exports rgw_file, a stateful API for file-oriented
  22 access to RGW buckets and objects.  The API is general, but its design
  23 is strongly influenced by the File System Abstraction Layer (FSAL) API
  24 of NFS-Ganesha, for which it has been primarily designed.
  25
  26 A set of Python bindings is also provided.
  27
  28 Namespace Conventions
  29 =====================
  30
  31 The implementation conforms to Amazon Web Services (AWS) hierarchical
  32 namespace conventions which map UNIX-style path names onto S3 buckets
  33 and objects.
  34
  35 The top level of the attached namespace consists of S3 buckets,
  36 represented as NFS directories. Files and directories subordinate to
  37 buckets are each represented as objects, following S3 prefix and
  38 delimiter conventions, with '/' being the only supported path
  39 delimiter [#]_.
  40
  41 For example, if an NFS client has mounted an RGW namespace at "/nfs",
  42 then a file "/nfs/mybucket/www/index.html" in the NFS namespace
  43 corresponds to an RGW object "www/index.html" in a bucket/container
  44 "mybucket."
  45
  46 Although it is generally invisible to clients, the NFS namespace is
  47 assembled through concatenation of the corresponding paths implied by
  48 the objects in the namespace.  Leaf objects, whether files or
  49 directories, will always be materialized in an RGW object of the
  50 corresponding key name, "<name>" if a file, "<name>/" if a directory.
  51 Non-leaf directories (e.g., "www" above) might only be implied by
  52 their appearance in the names of one or more leaf objects. Directories
  53 created within NFS or directly operated on by an NFS client (e.g., via
  54 an attribute-setting operation such as chown or chmod) always have a
  55 leaf object representation used to store materialized attributes such
  56 as Unix ownership and permissions.
  57
  58 Supported Operations
  59 ====================
  60
  61 The RGW NFS interface supports most operations on files and
  62 directories, with the following restrictions:
  63
  64 - Links, including symlinks, are not supported
  65 - NFS ACLs are not supported
  66
  67   + Unix user and group ownership and permissions *are* supported
  68
  69 - Directories may not be moved/renamed
  70
  71   + files may be moved between directories
  72
  73 - Only full, sequential *write* i/o is supported
  74
  75   + i.e., write operations are constrained to be **uploads**
  76   + many typical i/o operations such as editing files in place will necessarily fail as they perform non-sequential stores
  77   + some file utilities *apparently* writing sequentially (e.g., some versions of GNU tar) may fail due to infrequent non-sequential stores
  78   + When mounting via NFS, sequential application i/o can generally be constrained to be written sequentially to the NFS server via a synchronous mount option (e.g. -osync in Linux)
  79   + NFS clients which cannot mount synchronously (e.g., MS Windows) will not be able to upload files
  80
  81 Security
  82 ========
  83
  84 The RGW NFS interface provides a hybrid security model with the
  85 following characteristics:
  86
  87 - NFS protocol security is provided by the NFS-Ganesha server, as negotiated by the NFS server and clients
  88
  89   + e.g., clients can by trusted (AUTH_SYS), or required to present Kerberos user credentials (RPCSEC_GSS)
  90   + RPCSEC_GSS wire security can be integrity only (krb5i) or integrity and privacy (encryption, krb5p)
  91   + various NFS-specific security and permission rules are available
  92
  93     * e.g., root-squashing
  94
  95 - a set of RGW/S3 security credentials (unknown to NFS) is associated with each RGW NFS mount (i.e., NFS-Ganesha EXPORT)
  96
  97   + all RGW object operations performed via the NFS server will be performed by the RGW user associated with the credentials stored in the export being accessed (currently only RGW and RGW LDAP credentials are supported)
  98
  99     * additional RGW authentication types such as Keystone are not currently supported
 100
 101 Configuring an NFS-Ganesha Instance
 102 ===================================
 103
 104 Each NFS RGW instance is an NFS-Ganesha server instance *embeddding*
 105 a full Ceph RGW instance.
 106
 107 Therefore, the RGW NFS configuration includes Ceph and Ceph Object
 108 Gateway-specific configuration in a local ceph.conf, as well as
 109 NFS-Ganesha-specific configuration in the NFS-Ganesha config file,
 110 ganesha.conf.
 111
 112 ceph.conf
 113 ---------
 114
 115 Required ceph.conf configuration for RGW NFS includes:
 116
 117 * valid [client.radosgw.{instance-name}] section
 118 * valid values for minimal instance configuration, in particular, an installed and correct ``keyring``
 119
 120 Other config variables are optional, front-end-specific and front-end
 121 selection variables (e.g., ``rgw data`` and ``rgw frontends``) are
 122 optional and in some cases ignored.
 123
 124 A small number of config variables (e.g., ``rgw_namespace_expire_secs``)
 125 are unique to RGW NFS.
 126
 127 ganesha.conf
 128 ------------
 129
 130 A strictly minimal ganesha.conf for use with RGW NFS includes one
 131 EXPORT block with embedded FSAL block of type RGW::
 132
 133    EXPORT
 134    {
 135         Export_ID={numeric-id};
 136         Path = "/";
 137         Pseudo = "/";
 138         Access_Type = RW;
 139         SecType = "sys";
 140         NFS_Protocols = 4;
 141         Transport_Protocols = TCP;
 142
 143         # optional, permit unsquashed access by client "root" user
 144         #Squash = No_Root_Squash;
 145
 146         FSAL {
 147                 Name = RGW;
 148                 User_Id = {s3-user-id};
 149                 Access_Key_Id ="{s3-access-key}";
 150                 Secret_Access_Key = "{s3-secret}";
 151         }
 152    }
 153
 154 ``Export_ID`` must have an integer value, e.g., "77"
 155
 156 ``Path`` (for RGW) should be "/"
 157
 158 ``Pseudo`` defines an NFSv4 pseudo root name (NFSv4 only)
 159
 160 ``SecType = sys;`` allows clients to attach without Kerberos
 161 authentication
 162
 163 ``Squash = No_Root_Squash;`` enables the client root user to override
 164 permissions (Unix convention).  When root-squashing is enabled,
 165 operations attempted by the root user are performed as if by the local
 166 "nobody" (and "nogroup") user on the NFS-Ganesha server
 167
 168 The RGW FSAL additionally supports RGW-specific configuration
 169 variables in the RGW config section::
 170
 171  RGW {
 172      cluster = "{cluster name, default 'ceph'}";
 173      name = "client.rgw.{instance-name}";
 174      ceph_conf = "/opt/ceph-rgw/etc/ceph/ceph.conf";
 175      init_args = "-d --debug-rgw=16";
 176  }
 177
 178 ``cluster`` sets a Ceph cluster name (must match the cluster being exported)
 179
 180 ``name`` sets an RGW instance name (must match the cluster being exported)
 181
 182 ``ceph_conf`` gives a path to a non-default ceph.conf file to use
 183
 184
 185 Other useful NFS-Ganesha configuration:
 186 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 187
 188 Any EXPORT block which should support NFSv3 should include version 3
 189 in the NFS_Protocols setting. Additionally, NFSv3 is the last major
 190 version to support the UDP transport. To enable UDP, include it in the
 191 Transport_Protocols setting. For example::
 192
 193  EXPORT {
 194   ...
 195     NFS_Protocols = 3,4;
 196     Transport_Protocols = UDP,TCP;
 197   ...
 198  }
 199
 200 One important family of options pertains to interaction with the Linux
 201 idmapping service, which is used to normalize user and group names
 202 across systems.  Details of idmapper integration are not provided here.
 203
 204 With Linux NFS clients, NFS-Ganesha can be configured
 205 to accept client-supplied numeric user and group identifiers with
 206 NFSv4, which by default stringifies these--this may be useful in small
 207 setups and for experimentation::
 208
 209  NFSV4 {
 210      Allow_Numeric_Owners = true;
 211      Only_Numeric_Owners = true;
 212  }
 213
 214 Troubleshooting
 215 ~~~~~~~~~~~~~~~
 216
 217 NFS-Ganesha configuration problems are usually debugged by running the
 218 server with debugging options, controlled by the LOG config section.
 219
 220 NFS-Ganesha log messages are grouped into various components, logging
 221 can be enabled separately for each component. Valid values for
 222 component logging include::
 223
 224   *FATAL* critical errors only
 225   *WARN* unusual condition
 226   *DEBUG* mildly verbose trace output
 227   *FULL_DEBUG* verbose trace output
 228
 229 Example::
 230
 231   LOG {
 232
 233         Components {
 234                 MEMLEAKS = FATAL;
 235                 FSAL = FATAL;
 236                 NFSPROTO = FATAL;
 237                 NFS_V4 = FATAL;
 238                 EXPORT = FATAL;
 239                 FILEHANDLE = FATAL;
 240                 DISPATCH = FATAL;
 241                 CACHE_INODE = FATAL;
 242                 CACHE_INODE_LRU = FATAL;
 243                 HASHTABLE = FATAL;
 244                 HASHTABLE_CACHE = FATAL;
 245                 DUPREQ = FATAL;
 246                 INIT = DEBUG;
 247                 MAIN = DEBUG;
 248                 IDMAPPER = FATAL;
 249                 NFS_READDIR = FATAL;
 250                 NFS_V4_LOCK = FATAL;
 251                 CONFIG = FATAL;
 252                 CLIENTID = FATAL;
 253                 SESSIONS = FATAL;
 254                 PNFS = FATAL;
 255                 RW_LOCK = FATAL;
 256                 NLM = FATAL;
 257                 RPC = FATAL;
 258                 NFS_CB = FATAL;
 259                 THREAD = FATAL;
 260                 NFS_V4_ACL = FATAL;
 261                 STATE = FATAL;
 262                 FSAL_UP = FATAL;
 263                 DBUS = FATAL;
 264         }
 265         # optional: redirect log output
 266  #      Facility {
 267  #              name = FILE;
 268  #              destination = "/tmp/ganesha-rgw.log";
 269  #              enable = active;
 270         }
 271  }
 272
 273 Running Multiple NFS Gateways
 274 =============================
 275
 276 Each NFS-Ganesha instance acts as a full gateway endpoint, with the
 277 limitation that currently an NFS-Ganesha instance cannot be configured
 278 to export HTTP services. As with ordinary gateway instances, any
 279 number of NFS-Ganesha instances can be started, exporting the same or
 280 different resources from the cluster. This enables the clustering of
 281 NFS-Ganesha instances. However, this does not imply high availability.
 282
 283 When regular gateway instances and NFS-Ganesha instances overlap the
 284 same data resources, they will be accessible from both the standard S3
 285 API and through the NFS-Ganesha instance as exported. You can
 286 co-locate the NFS-Ganesha instance with a Ceph Object Gateway instance
 287 on the same host.
 288
 289 RGW vs RGW NFS
 290 ==============
 291
 292 Exporting an NFS namespace and other RGW namespaces (e.g., S3 or Swift
 293 via the Civetweb HTTP front-end) from the same program instance is
 294 currently not supported.
 295
 296 When adding objects and buckets outside of NFS, those objects will
 297 appear in the NFS namespace in the time set by
 298 ``rgw_nfs_namespace_expire_secs``, which defaults to 300 seconds (5 minutes).
 299 Override the default value for ``rgw_nfs_namespace_expire_secs`` in the
 300 Ceph configuration file to change the refresh rate.
 301
 302 If exporting Swift containers that do not conform to valid S3 bucket
 303 naming requirements, set ``rgw_relaxed_s3_bucket_names`` to true in the
 304 [client.radosgw] section of the Ceph configuration file. For example,
 305 if a Swift container name contains underscores, it is not a valid S3
 306 bucket name and will be rejected unless ``rgw_relaxed_s3_bucket_names``
 307 is set to true.
 308
 309 Configuring NFSv4 clients
 310 =========================
 311
 312 To access the namespace, mount the configured NFS-Ganesha export(s)
 313 into desired locations in the local POSIX namespace. As noted, this
 314 implementation has a few unique restrictions:
 315
 316 - NFS 4.1 and higher protocol flavors are preferred
 317
 318   + NFSv4 OPEN and CLOSE operations are used to track upload transactions
 319
 320 - To upload data successfully, clients must preserve write ordering
 321
 322   + on Linux and many Unix NFS clients, use the -osync mount option
 323
 324 Conventions for mounting NFS resources are platform-specific. The
 325 following conventions work on Linux and some Unix platforms:
 326
 327 From the command line::
 328
 329   mount -t nfs -o nfsvers=4,noauto,soft,proto=tcp <ganesha-host-name>:/ <mount-point>
 330
 331 In /etc/fstab::
 332
 333 <ganesha-host-name>:/ <mount-point> nfs noauto,soft,nfsvers=4.1,sync,proto=tcp 0 0
 334
 335 Specify the NFS-Ganesha host name and the path to the mount point on
 336 the client.
 337
 338 Configuring NFSv3 Clients
 339 =========================
 340
 341 Linux clients can be configured to mount with NFSv3 by supplying
 342 ``nfsvers=3`` and ``noacl`` as mount options. To use UDP as the
 343 transport, add ``proto=udp`` to the mount options. However, TCP is the
 344 preferred transport::
 345
 346   <ganesha-host-name>:/ <mount-point> nfs noauto,noacl,soft,nfsvers=3,sync,proto=tcp 0 0
 347
 348 Configure the NFS Ganesha EXPORT block Protocols setting with version
 349 3 and the Transports setting with UDP if the mount will use version 3 with UDP.
 350
 351 NFSv3 Semantics
 352 ---------------
 353
 354 Since NFSv3 does not communicate client OPEN and CLOSE operations to
 355 file servers, RGW NFS cannot use these operations to mark the
 356 beginning and ending of file upload transactions. Instead, RGW NFS
 357 starts a new upload when the first write is sent to a file at offset
 358 0, and finalizes the upload when no new writes to the file have been
 359 seen for a period of time, by default, 10 seconds. To change this
 360 timeout, set an alternate value for ``rgw_nfs_write_completion_interval_s``
 361 in the RGW section(s) of the Ceph configuration file.
 362
 363 References
 364 ==========
 365
 366 .. [#] http://docs.aws.amazon.com/AmazonS3/latest/dev/ListingKeysHierarchy.html