From patchwork Tue Jun 3 06:20:08 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Qu Wenruo X-Patchwork-Id: 4285241 X-Patchwork-Delegate: dave@jikos.cz Return-Path: X-Original-To: patchwork-linux-btrfs@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.19.201]) by patchwork2.web.kernel.org (Postfix) with ESMTP id A8319BEEA7 for ; Tue, 3 Jun 2014 06:19:14 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 89A2E201DD for ; Tue, 3 Jun 2014 06:19:13 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 88482201C8 for ; Tue, 3 Jun 2014 06:19:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932076AbaFCGTI (ORCPT ); Tue, 3 Jun 2014 02:19:08 -0400 Received: from cn.fujitsu.com ([59.151.112.132]:41414 "EHLO heian.cn.fujitsu.com" rhost-flags-OK-FAIL-OK-FAIL) by vger.kernel.org with ESMTP id S1752351AbaFCGTG (ORCPT ); Tue, 3 Jun 2014 02:19:06 -0400 X-IronPort-AV: E=Sophos;i="4.98,963,1392134400"; d="scan'208";a="31365607" Received: from unknown (HELO edo.cn.fujitsu.com) ([10.167.33.5]) by heian.cn.fujitsu.com with ESMTP; 03 Jun 2014 14:16:28 +0800 Received: from G08CNEXCHPEKD02.g08.fujitsu.local (localhost.localdomain [127.0.0.1]) by edo.cn.fujitsu.com (8.14.3/8.13.1) with ESMTP id s536J4UD013419 for ; Tue, 3 Jun 2014 14:19:04 +0800 Received: from adam-work.lan (10.167.226.24) by G08CNEXCHPEKD02.g08.fujitsu.local (10.167.33.89) with Microsoft SMTP Server (TLS) id 14.3.181.6; Tue, 3 Jun 2014 14:19:08 +0800 From: Qu Wenruo To: Subject: [PATCH] btrfs-progs: Documentation: Add filter section for btrfs-balance. Date: Tue, 3 Jun 2014 14:20:08 +0800 Message-ID: <1401776408-32699-1-git-send-email-quwenruo@cn.fujitsu.com> X-Mailer: git-send-email 1.9.3 MIME-Version: 1.0 X-Originating-IP: [10.167.226.24] Sender: linux-btrfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-btrfs@vger.kernel.org X-Spam-Status: No, score=-7.5 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Man page for 'btrfs-balance' mentioned but does not explain them, which make end users hard to use '-d', '-m' or '-s options. This patch will use the explanations from https://btrfs.wiki.kernel.org/index.php/Balance_Filters to enrich the man page. Signed-off-by: Qu Wenruo --- Documentation/btrfs-balance.txt | 60 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 57 insertions(+), 3 deletions(-) diff --git a/Documentation/btrfs-balance.txt b/Documentation/btrfs-balance.txt index 37d8781..de93c92 100644 --- a/Documentation/btrfs-balance.txt +++ b/Documentation/btrfs-balance.txt @@ -37,11 +37,11 @@ given balance all chunks in a filesystem. `Options` + -d[]:::: -act on data chunks +act on data chunks. See `FILTERS` section for details about . -m[]:::: -act on metadata chunks +act on metadata chunks. See `FILTERS` section for details about . -s[]:::: -act on system chunks (only under -f) +act on system chunks (only under -f). See `FILTERS` section for details about . -v:::: be verbose -f:::: @@ -61,6 +61,60 @@ Show status of running or paused balance. + If '-v' option is given, output will be verbose. +FILTERS +------- +From kernel 3.3 onwards, btrfs balance can limit its action to a subset of the +full filesystem, and can be used to change the replication configuration (e.g. +moving data from single to RAID-1). This functionality is accessed through the +'-d', '-m' or '-s' options to btrfs balance start, which filter on data, +metadata and system blocks respectively. + +A filter has the following stucture: :: +'type'[='params'][,'type'=...] + +The available types are: :: +*profiles*:::: +Balances only block groups with the given replication profiles. Parameters +are a list of profile names separated by |. + +*usage*:::: +Balances only block groups with usage under the given percentage. The +value of 0 is allowed and will clean up completely unused block groups, this +should not require any new space allocated. You may want to use usage=0 in +case balance is returnin ENOSPC and your filesystem is not too full. + +*devid*:::: +Balances only block groups which have at least one chunk on the given +device (by btrfs device ID -- use btrfs fi show to list device IDs) + +*drange*:::: +Balances only block groups which overlap with the given byte range on any +device. (Use in conjunction with "devid" to filter on a specific device). The +parameter is a range specified as . + +*vrange*:::: +Balances only block groups which overlap with the given byte range in the +filesystem's internal virtual address space. This is the address space that +most reports from btrfs in the kernel log use. The parameter is a range +specified as . + +*convert*:::: +Convert each selected block group to the given profile name identified by +parameters. + +*soft*:::: +Takes no parameters. Only has meaning when converting between profiles. +When doing convert from one profile to another and soft mode is on, +restriper won't touch chunks that already have the target profile. This is +useful if e.g. half of the FS was converted earlier. ++ +The soft mode switch is (like every other filter) per-type. This means +that we can convert for example meta chunks the "hard" way while converting +data chunks selectively with soft switch. + +Profile names, used in profiles and convert are one of: 'raid0', 'raid1', +'raid10', 'raid5', 'raid6', 'dup', 'single'. + EXIT STATUS ----------- *btrfs balance* returns a zero exist status if it succeeds. Non zero is