From patchwork Thu Apr 12 15:08:26 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Miklos Szeredi X-Patchwork-Id: 10338691 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 B333560134 for ; Thu, 12 Apr 2018 15:09:44 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id A8CF026E74 for ; Thu, 12 Apr 2018 15:09:44 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 9DBCF26E78; Thu, 12 Apr 2018 15:09:44 +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=-7.9 required=2.0 tests=BAYES_00, MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=unavailable 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 45F4526E76 for ; Thu, 12 Apr 2018 15:09:44 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752929AbeDLPJ3 (ORCPT ); Thu, 12 Apr 2018 11:09:29 -0400 Received: from mail-wr0-f194.google.com ([209.85.128.194]:44687 "EHLO mail-wr0-f194.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753798AbeDLPJN (ORCPT ); Thu, 12 Apr 2018 11:09:13 -0400 Received: by mail-wr0-f194.google.com with SMTP id u46so5466987wrc.11 for ; Thu, 12 Apr 2018 08:09:13 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=2zb9t90b16gHbTWNfEqSM1NfNVMzdj61lixBd5oltGc=; b=ZTLIlXw8A4DXG26rm8J2UXPyowOtyifAkQeyRmxqCrunrmj5dOujz4IMW7CGkYjmbP IrRYiHcDdvr05cV9T/nh1myxgW++MEqPAq5v+clZMWr4xg3cMFSsY502KFTBy9UuYW+9 7KwZAAPFhhRrDw61/n7/YGsaz64hlY+1o8ne+HZLN6cYlBnUMyvr/NNH9vKpwLtQ2iDo +jaL5lmwljyyiUdOzAOGt2Tbvr/Q8HXCE/gcaAbYDCcA5ajAD8+EROYkFkVMHLudisah IqFkyB0Hs4nSRENKb+qi3OsvJb6dnkL477uMOtSChFT0Jd5Ezg/BqbWqLjlOoOHB8YeG CiSw== X-Gm-Message-State: ALQs6tBnJpknkcrQccTWeAN7eua8f8FzFARwh9u9l9wrWwmOp3W4nZZh sOBpeLPa7HpT2BLPiinWSWqZCg== X-Google-Smtp-Source: AIpwx4//SUUGCMkfB8dR6BLYp1JC6JS7wJ27DRCrx8xP1CPgyqRpOy7R00pIdLKziTS0eTlW23CKZQ== X-Received: by 10.223.185.76 with SMTP id b12mr1112419wrg.205.1523545752529; Thu, 12 Apr 2018 08:09:12 -0700 (PDT) Received: from veci.piliscsaba.redhat.com (catv-176-63-54-97.catv.broadband.hu. [176.63.54.97]) by smtp.gmail.com with ESMTPSA id p197sm2621783wme.43.2018.04.12.08.09.11 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 12 Apr 2018 08:09:11 -0700 (PDT) From: Miklos Szeredi To: linux-unionfs@vger.kernel.org Cc: linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [RFC PATCH 35/35] ovl: fix documentation of non-standard behavior Date: Thu, 12 Apr 2018 17:08:26 +0200 Message-Id: <20180412150826.20988-36-mszeredi@redhat.com> X-Mailer: git-send-email 2.14.3 In-Reply-To: <20180412150826.20988-1-mszeredi@redhat.com> References: <20180412150826.20988-1-mszeredi@redhat.com> Sender: linux-fsdevel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fsdevel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP We can now drop description of the ro/rw inconsistency from the documentation. Also clarify, that now fully standard compliant behavior can be enabled with kernel/module/mount options. Signed-off-by: Miklos Szeredi --- Documentation/filesystems/overlayfs.txt | 64 ++++++++++++++++++++++----------- 1 file changed, 43 insertions(+), 21 deletions(-) diff --git a/Documentation/filesystems/overlayfs.txt b/Documentation/filesystems/overlayfs.txt index 961b287ef323..095186080d23 100644 --- a/Documentation/filesystems/overlayfs.txt +++ b/Documentation/filesystems/overlayfs.txt @@ -306,27 +306,49 @@ the copied layers will fail the verification of the lower root file handle. Non-standard behavior --------------------- -The copy_up operation essentially creates a new, identical file and -moves it over to the old name. Any open files referring to this inode -will access the old data. - -The new file may be on a different filesystem, so both st_dev and st_ino -of the real file may change. The values of st_dev and st_ino returned by -stat(2) on an overlay object are often not the same as the real file -stat(2) values to prevent the values from changing on copy_up. - -Unless "xino" feature is enabled, when overlay layers are not all on the -same underlying filesystem, the value of st_dev may be different for two -non-directory objects in the same overlay filesystem and the value of -st_ino for directory objects may be non persistent and could change even -while the overlay filesystem is still mounted. - -Unless "inode index" feature is enabled, if a file with multiple hard -links is copied up, then this will "break" the link. Changes will not be -propagated to other names referring to the same inode. - -Unless "redirect_dir" feature is enabled, rename(2) on a lower or merged -directory will fail with EXDEV. +Overlayfs can now act as a POSIX compliant filesystem with the following +features turned on: + +1) "redirect_dir" + +Enabled with the mount option or module option: "redirect_dir=on" or with +the kernel config option CONFIG_OVERLAY_FS_REDIRECT_DIR=y. + +If this feature is disabled, then rename(2) on a lower or merged directory +will fail with EXDEV ("Invalid cross-device link"). + +2) "inode index" + +Enabled with the mount option or module option "index=on" or with the +kernel config option CONFIG_OVERLAY_FS_INDEX=y. + +If this feature is disabled and a file with multiple hard links is copied +up, then this will "break" the link. Changes will not be propagated to +other names referring to the same inode. + +3) "xino" + +Enabled with the mount option "xino=auto" or "xino=on", with the module +option "xino_auto=on" or with the kernel config option +CONFIG_OVERLAY_FS_XINO_AUTO=y. Also implicitly enabled by using the same +underlying filesystem for all layers making up the overlay. + +If this feature is disabled or the underlying filesystem doesn't have +enough free bits in the inode number, then overlayfs will not be able to +guarantee that the values of st_ino and st_dev returned by stat(2) and the +value of d_ino returned by readdir(3) will act like on a normal filesystem. +E.g. the value of st_dev may be different for two objects in the same +overlay filesystem and the value of st_ino for directory objects may not be +persistent and could change even while the overlay filesystem is mounted. + +4) "copy_up_shared" + +Enabled with the mount option or module option "copy_up_shared=on" or with +the kernel config option CONFIG_OVERLAY_FS_COPY_UP_SHARED=y. + +If this feature is disabled, then a memory mapping created with MAP_SHARED +might contain stale data if the file has been copied up and modified in the +meantime. Changes to underlying filesystems