From nobody Sat May 4 12:28:40 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1620244620; cv=none; d=zohomail.com; s=zohoarc; b=WkYzyuuRqYUNY7LSfZgFytavVLcc8M7csinSwN8+b8qJ5mujYGHyYkB/hFOYbniT31GJDRHWvMFvPbuheZ3EyOAYSD2b8SuFu5UerZCpuVxk/BXRrTA7XXrPx0kKXhv8mbhCX4bzPJuG2kSHMm2Vsz7mLMjE70NCzIBwoh7ns64= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1620244620; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:To; bh=SMRKZ6atiGdLFg7up4QwzHhKeurpEUVx7j4qVVR/UxA=; b=JNipkNI7Cxk8Ct4eAFrEY6BfyxPp+EvmZq9CtkCoCMiEkXvf6/GkuIXOQ0H/C6Xe0kkjaAO+06cS8zFH/Lp1irY+hZzIEueSoWroJgjPLLMphDwniLKh8OrolYaXmtPvNszSIMuWa1BWxLu2DczR24/aDyVFeL6lwFX3usmmthc= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 162024462040826.84176562256698; Wed, 5 May 2021 12:57:00 -0700 (PDT) Received: from localhost ([::1]:46224 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1leNdj-0007OB-CH for importer@patchew.org; Wed, 05 May 2021 15:56:59 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51452) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1leNc9-0006Sq-K9 for qemu-devel@nongnu.org; Wed, 05 May 2021 15:55:23 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:58074) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1leNc5-0008WS-RI for qemu-devel@nongnu.org; Wed, 05 May 2021 15:55:21 -0400 Received: from mail-oi1-f199.google.com (mail-oi1-f199.google.com [209.85.167.199]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-517--51Nq0WwNZ-zKZ147SyMBg-1; Wed, 05 May 2021 15:55:14 -0400 Received: by mail-oi1-f199.google.com with SMTP id u2-20020aca60020000b02901e51e89c211so1407009oib.15 for ; Wed, 05 May 2021 12:55:14 -0700 (PDT) Received: from redhat.redhat.com (ip68-103-222-6.ks.ok.cox.net. [68.103.222.6]) by smtp.gmail.com with ESMTPSA id o6sm33698oih.44.2021.05.05.12.55.12 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 05 May 2021 12:55:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1620244516; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=SMRKZ6atiGdLFg7up4QwzHhKeurpEUVx7j4qVVR/UxA=; b=DNKVbKeDsTmCpGTbSPtTxrEDPyZ44N6rBOhh/vJG8zPnzWHxZ5Aa64Kr7NqXj314ZVxihs /E+xdYb+qIkcIkDJPEFma5XtgDfjAN/1YMLw3zT6LZ70tmEmYDmAwHVzloZmcpVSWmfGui jyQGcXYbdnyg0EdubdoA4mwy+gsX1i4= X-MC-Unique: -51Nq0WwNZ-zKZ147SyMBg-1 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:mime-version :content-transfer-encoding; bh=SMRKZ6atiGdLFg7up4QwzHhKeurpEUVx7j4qVVR/UxA=; b=RwDWZ4GfPYidSRTHkmUO/cDsIpLmBE+xUu5sI9Ldibcv1o18mpwPojEJaXqbc2LG32 viHmVv8b9sUw+ehrkYZg4UEgkehFaZlMr6sS5Og2wgqQyRhpEUZClHt8ZbPr94c2OZVB /py2Dzp5YEsMUhgMb0jFhb7yWfA2WE49T2f/+HotR0WGZYPSo5K8v4P3QPmJroFLlUbW WleYaVo4FMZwnTQjgRFCtSug+Go7sCHjFe2vosvpBKTpt9BfR3TLMa6qAnJFHQr06xRT v9Tt0gcoI0nKgO6+nuo3vQ1Gw+Kp6TCuSxmMFRlfD7i+Nrq2TuLfuP+EsGzhZ5yWAk6Z rgkw== X-Gm-Message-State: AOAM5319SUJ4jBzb20Uquqd4+Bp/rB/0pX89kEJEnUJRvsWKUyHaf8n3 J39TCJH5pH7TdcdXwuqb7P2pdPCjnjK4YLxpks1tBmkXbhivLTcv8IbIbj6xCl8jH8+5Xc3+4I9 WjthbK1jmZakZOeI= X-Received: by 2002:aca:f245:: with SMTP id q66mr422303oih.179.1620244513731; Wed, 05 May 2021 12:55:13 -0700 (PDT) X-Google-Smtp-Source: ABdhPJzgvf1I0asMHGK5Bd/ypOqSKZqWjPTTh35ZIcLH2cy+7iwODaCJDynmqqdTHjHBg2vsgzFDlQ== X-Received: by 2002:aca:f245:: with SMTP id q66mr422294oih.179.1620244513545; Wed, 05 May 2021 12:55:13 -0700 (PDT) From: Connor Kuehl To: qemu-block@nongnu.org Subject: [PATCH v3] Document qemu-img options data_file and data_file_raw Date: Wed, 5 May 2021 14:55:12 -0500 Message-Id: <20210505195512.391128-1-ckuehl@redhat.com> X-Mailer: git-send-email 2.30.2 MIME-Version: 1.0 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ckuehl@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=216.205.24.124; envelope-from=ckuehl@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.693, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Kevin Wolf , John Snow , qemu-devel@nongnu.org, Max Reitz Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) The contents of this patch were initially developed and posted by Han Han[1], however, it appears the original patch was not applied. Since then, the relevant documentation has been moved and adapted to a new format. I've taken most of the original wording and tweaked it according to some of the feedback from the original patch submission. I've also adapted it to restructured text, which is the format the documentation currently uses. [1] https://lists.nongnu.org/archive/html/qemu-block/2019-10/msg01253.html Fixes: https://bugzilla.redhat.com/1763105 Signed-off-by: Han Han Suggested-by: Max Reitz [ Max: provided description of data_file_raw behavior ] Signed-off-by: Connor Kuehl --- John, my apologies, I failed to CC you on my last revision (v2) where I addressed your comments. Changes since v2: * Pulled in Max's explanation of data_file_raw behaviors with some minor wording tweaks. Changes since v1: * Clarify different behaviors with these options when using qemu-img create vs amend (Max) * Touch on the negative case of how the file becomes inconsistent (John) docs/tools/qemu-img.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/tools/qemu-img.rst b/docs/tools/qemu-img.rst index c9efcfaefc..cfe1147879 100644 --- a/docs/tools/qemu-img.rst +++ b/docs/tools/qemu-img.rst @@ -866,6 +866,37 @@ Supported image file formats: issue ``lsattr filename`` to check if the NOCOW flag is set or not (Capital 'C' is NOCOW flag). =20 + ``data_file`` + Filename where all guest data will be stored. If this option is used, + the qcow2 file will only contain the image's metadata. + + Note: Data loss will occur if the given filename already exists when + using this option with ``qemu-img create`` since ``qemu-img`` will cre= ate + the data file anew, overwriting the file's original contents. To simply + update the reference to point to the given pre-existing file, use + ``qemu-img amend``. + + ``data_file_raw`` + If this option is set to ``on``, QEMU will always keep the external da= ta + file consistent as a standalone read-only raw image. + + It does this by forwarding all write accesses to the qcow2 file throug= h to + the raw data file, including their offsets. Therefore, data that is vi= sible + on the qcow2 node (i.e., to the guest) at some offset is visible at th= e same + offset in the raw data file. This results in a read-only raw image. Wr= ites + that bypass the qcow2 metadata may corrupt the qcow2 metadata because = the + out-of-band writes may result in the metadata falling out of sync with= the + raw image. + + If this option is ``off``, QEMU will use the data file to store data i= n an + arbitrary manner. The file=E2=80=99s content will not make sense witho= ut the + accompanying qcow2 metadata. Where data is written will have no relati= on to + its offset as seen by the guest, and some writes (specifically zero wr= ites) + may not be forwarded to the data file at all, but will only be handled= by + modifying qcow2 metadata. + + This option can only be enabled if ``data_file`` is set. + ``Other`` =20 QEMU also supports various other image file formats for --=20 2.30.2