| Message ID | 1397184233-18535-1-git-send-email-quwenruo@cn.fujitsu.com (mailing list archive) |
|---|---|
| State | Accepted |
| Headers | show |
On Fri, Apr 11, 2014 at 10:43:52AM +0800, Qu Wenruo wrote: > Add device management related paragraph to better explain btrfs device > management. Thank you for these updates. > Cc: Marc MERLIN <marc@merlins.org> > Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com> (comments below) > --- > Documentation/btrfs-balance.txt | 3 +++ > Documentation/btrfs-device.txt | 42 +++++++++++++++++++++++++++++++++++++++++ > Documentation/btrfs-replace.txt | 4 ++++ > 3 files changed, 49 insertions(+) > > diff --git a/Documentation/btrfs-balance.txt b/Documentation/btrfs-balance.txt > index 2289fdf..1b1861c 100644 > --- a/Documentation/btrfs-balance.txt > +++ b/Documentation/btrfs-balance.txt > @@ -14,6 +14,8 @@ DESCRIPTION > 'btrfs balance' is used to balance chunks in a btrfs filesystem across > multiple or even single device. > > +See `btrfs-device`(8) for more details about the effect on device management. > + > SUBCOMMAND > ---------- > <path>:: > @@ -75,3 +77,4 @@ further details. > SEE ALSO > -------- > `mkfs.btrfs`(8), > +`btrfs-device`(8) > diff --git a/Documentation/btrfs-device.txt b/Documentation/btrfs-device.txt > index 20d7bcd..474d411 100644 > --- a/Documentation/btrfs-device.txt > +++ b/Documentation/btrfs-device.txt > @@ -14,6 +14,46 @@ DESCRIPTION > 'btrfs device' is used to control the btrfs devices, since btrfs can be used > across several devices, 'btrfs device' is used for multiple device management. > > +DEVICE MANAGEMENT > +----------------- > +Btrfs filesystem is capable to manage multiple devices. > + > +Btrfs filesystem use different profiles to manage different RAID level, and > +use balance to rebuild chunks, also devices can be added/removed/replace > +online. > + > +Profile:: > +Btrfs filesystem use data/metadata profiles to manage allocation/duplication > +mechanism. Profiles like RAID level can be assigned to data and metadata separately. > ++ > +See `mkfs.btrfs`(8) for more details. > + > +RAID level:: > +Btrfs filesystem supports most of the standard RAID level: 0/1/5/6/10. > +RAID levels can be assigned at mkfs time or online. > ++ > +See `mkfs.btrfs`(8) for mkfs time RAID level assign and `btrfs-balance`(8) for > +online RAID level assign. > + > +Balance:: > +`btrfs-balance`(8) subcommand can be used to balance or rebuild chunks to the > +desired profile. > ++ > +Due to the fact that balance can rebuild/recovery chunks according to its RAID > +duplication if possible, so when using RAID1/5/6/10 with some devices failed > +and you just added a new device to btrfs using `btrfs-device`(8), you should > +run `btrfs-balance`(8) to rebuild the chunks. > ++ > +See `btrfs-balance`(8) for more details. > + > +Device add/remove/replace:: > +Device can be added/removed using `btrfs-replace`(8) subcommand and replaced > +using `btrfs-replace`(8). I'm not sure I understand this sentence exactly. > +When device is removed or replaced, btrfs will do the chunk rebuild if needed. > ++ > +See `btrfs-replace`(8) and this man page for more details. > + > SUBCOMMAND > ---------- > 'add' [-Kf] <dev> [<dev>...] <path>:: > @@ -73,3 +113,5 @@ further details. > SEE ALSO > -------- > `mkfs.btrfs`(8), > +`btrfs-replace`(8), > +`btrfs-balance`(8) > diff --git a/Documentation/btrfs-replace.txt b/Documentation/btrfs-replace.txt > index 8c5dcc4..15a46c2 100644 > --- a/Documentation/btrfs-replace.txt > +++ b/Documentation/btrfs-replace.txt > @@ -13,6 +13,9 @@ DESCRIPTION > ----------- > 'btrfs replace' is used to replace btrfs managed devices with other device. I would add a quick line here saying that it's not currently supported for RAID5/6, and to see btrfs-device for add/delete to get around the replace missing problem. I've explained that in more details on https://btrfs.wiki.kernel.org/index.php/FAQ#Can_I_use_RAID.5B56.5D_on_my_Btrfs_filesystem.3F but it may not be a great page to link to. Ok, I just made a new nice page for you: https://btrfs.wiki.kernel.org/index.php/RAID56 Do you think it would be ok to link to https://btrfs.wiki.kernel.org/index.php/RAID56#Parity_Rebuilds_and_Advanced_Disk_Replacement in the btrfs replace man page? > +It is recommended to see `btrfs-device`(8) for more details about btrfs device > +management. > + > SUBCOMMAND > ---------- > 'start' [-Bfr] <srcdev>|<devid> <targetdev> <path>:: > @@ -74,3 +77,4 @@ further details. > SEE ALSO > -------- > `mkfs.btrfs`(8), > +`btrfs-device`(8), > -- > 1.9.2 The rest looks good. Thank you, Marc
-------- Original Message -------- Subject: Re: [PATCH 1/2] btrfs-progs: Add device management related paragraph. From: Marc MERLIN <marc@merlins.org> To: Qu Wenruo <quwenruo@cn.fujitsu.com> Date: 2014?04?11? 14:10 > On Fri, Apr 11, 2014 at 10:43:52AM +0800, Qu Wenruo wrote: >> Add device management related paragraph to better explain btrfs device >> management. > Thank you for these updates. > >> Cc: Marc MERLIN <marc@merlins.org> >> Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com> > (comments below) > >> --- >> Documentation/btrfs-balance.txt | 3 +++ >> Documentation/btrfs-device.txt | 42 +++++++++++++++++++++++++++++++++++++++++ >> Documentation/btrfs-replace.txt | 4 ++++ >> 3 files changed, 49 insertions(+) >> >> diff --git a/Documentation/btrfs-balance.txt b/Documentation/btrfs-balance.txt >> index 2289fdf..1b1861c 100644 >> --- a/Documentation/btrfs-balance.txt >> +++ b/Documentation/btrfs-balance.txt >> @@ -14,6 +14,8 @@ DESCRIPTION >> 'btrfs balance' is used to balance chunks in a btrfs filesystem across >> multiple or even single device. >> >> +See `btrfs-device`(8) for more details about the effect on device management. >> + >> SUBCOMMAND >> ---------- >> <path>:: >> @@ -75,3 +77,4 @@ further details. >> SEE ALSO >> -------- >> `mkfs.btrfs`(8), >> +`btrfs-device`(8) >> diff --git a/Documentation/btrfs-device.txt b/Documentation/btrfs-device.txt >> index 20d7bcd..474d411 100644 >> --- a/Documentation/btrfs-device.txt >> +++ b/Documentation/btrfs-device.txt >> @@ -14,6 +14,46 @@ DESCRIPTION >> 'btrfs device' is used to control the btrfs devices, since btrfs can be used >> across several devices, 'btrfs device' is used for multiple device management. >> >> +DEVICE MANAGEMENT >> +----------------- >> +Btrfs filesystem is capable to manage multiple devices. >> + >> +Btrfs filesystem use different profiles to manage different RAID level, and >> +use balance to rebuild chunks, also devices can be added/removed/replace >> +online. >> + >> +Profile:: >> +Btrfs filesystem use data/metadata profiles to manage allocation/duplication >> +mechanism. Profiles like RAID level can be assigned to data and metadata separately. >> ++ >> +See `mkfs.btrfs`(8) for more details. >> + >> +RAID level:: >> +Btrfs filesystem supports most of the standard RAID level: 0/1/5/6/10. >> +RAID levels can be assigned at mkfs time or online. >> ++ >> +See `mkfs.btrfs`(8) for mkfs time RAID level assign and `btrfs-balance`(8) for >> +online RAID level assign. >> + >> +Balance:: >> +`btrfs-balance`(8) subcommand can be used to balance or rebuild chunks to the >> +desired profile. >> ++ >> +Due to the fact that balance can rebuild/recovery chunks according to its RAID >> +duplication if possible, so when using RAID1/5/6/10 with some devices failed >> +and you just added a new device to btrfs using `btrfs-device`(8), you should >> +run `btrfs-balance`(8) to rebuild the chunks. >> ++ >> +See `btrfs-balance`(8) for more details. >> + >> +Device add/remove/replace:: >> +Device can be added/removed using `btrfs-replace`(8) subcommand and replaced >> +using `btrfs-replace`(8). > I'm not sure I understand this sentence exactly. Sorry for my poor English, I'll try to change it to a better expression. > >> +When device is removed or replaced, btrfs will do the chunk rebuild if needed. >> ++ >> +See `btrfs-replace`(8) and this man page for more details. >> + >> SUBCOMMAND >> ---------- >> 'add' [-Kf] <dev> [<dev>...] <path>:: >> @@ -73,3 +113,5 @@ further details. >> SEE ALSO >> -------- >> `mkfs.btrfs`(8), >> +`btrfs-replace`(8), >> +`btrfs-balance`(8) >> diff --git a/Documentation/btrfs-replace.txt b/Documentation/btrfs-replace.txt >> index 8c5dcc4..15a46c2 100644 >> --- a/Documentation/btrfs-replace.txt >> +++ b/Documentation/btrfs-replace.txt >> @@ -13,6 +13,9 @@ DESCRIPTION >> ----------- >> 'btrfs replace' is used to replace btrfs managed devices with other device. > I would add a quick line here saying that it's not currently supported for > RAID5/6, and to see btrfs-device for add/delete to get around the replace > missing problem. > > I've explained that in more details on > https://btrfs.wiki.kernel.org/index.php/FAQ#Can_I_use_RAID.5B56.5D_on_my_Btrfs_filesystem.3F > but it may not be a great page to link to. > Ok, I just made a new nice page for you: > https://btrfs.wiki.kernel.org/index.php/RAID56 > > Do you think it would be ok to link to > https://btrfs.wiki.kernel.org/index.php/RAID56#Parity_Rebuilds_and_Advanced_Disk_Replacement > in the btrfs replace man page? That's very nice for you making a new wiki page. IMO it's OK to link to the URL. Thanks, Qu > >> +It is recommended to see `btrfs-device`(8) for more details about btrfs device >> +management. >> + >> SUBCOMMAND >> ---------- >> 'start' [-Bfr] <srcdev>|<devid> <targetdev> <path>:: >> @@ -74,3 +77,4 @@ further details. >> SEE ALSO >> -------- >> `mkfs.btrfs`(8), >> +`btrfs-device`(8), >> -- >> 1.9.2 > The rest looks good. > > Thank you, > Marc -- To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Fri, Apr 11, 2014 at 10:43:52AM +0800, Qu Wenruo wrote: > Add device management related paragraph to better explain btrfs device > management. > > Cc: Marc MERLIN <marc@merlins.org> > Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com> > --- > Documentation/btrfs-balance.txt | 3 +++ > Documentation/btrfs-device.txt | 42 +++++++++++++++++++++++++++++++++++++++++ > Documentation/btrfs-replace.txt | 4 ++++ > 3 files changed, 49 insertions(+) > > diff --git a/Documentation/btrfs-balance.txt b/Documentation/btrfs-balance.txt > index 2289fdf..1b1861c 100644 > --- a/Documentation/btrfs-balance.txt > +++ b/Documentation/btrfs-balance.txt > @@ -14,6 +14,8 @@ DESCRIPTION > 'btrfs balance' is used to balance chunks in a btrfs filesystem across > multiple or even single device. > > +See `btrfs-device`(8) for more details about the effect on device management. > + > SUBCOMMAND > ---------- > <path>:: > @@ -75,3 +77,4 @@ further details. > SEE ALSO > -------- > `mkfs.btrfs`(8), > +`btrfs-device`(8) > diff --git a/Documentation/btrfs-device.txt b/Documentation/btrfs-device.txt > index 20d7bcd..474d411 100644 > --- a/Documentation/btrfs-device.txt > +++ b/Documentation/btrfs-device.txt > @@ -14,6 +14,46 @@ DESCRIPTION > 'btrfs device' is used to control the btrfs devices, since btrfs can be used > across several devices, 'btrfs device' is used for multiple device management. > > +DEVICE MANAGEMENT > +----------------- > +Btrfs filesystem is capable to manage multiple devices. > + > +Btrfs filesystem use different profiles to manage different RAID level, and > +use balance to rebuild chunks, also devices can be added/removed/replace > +online. s/use/uses/g > + > +Profile:: > +Btrfs filesystem use data/metadata profiles to manage allocation/duplication > +mechanism. Profiles like RAID level can be assigned to data and metadata separately. ditto. Good update. -liubo > ++ > +See `mkfs.btrfs`(8) for more details. > + > +RAID level:: > +Btrfs filesystem supports most of the standard RAID level: 0/1/5/6/10. > +RAID levels can be assigned at mkfs time or online. > ++ > +See `mkfs.btrfs`(8) for mkfs time RAID level assign and `btrfs-balance`(8) for > +online RAID level assign. > + > +Balance:: > +`btrfs-balance`(8) subcommand can be used to balance or rebuild chunks to the > +desired profile. > ++ > +Due to the fact that balance can rebuild/recovery chunks according to its RAID > +duplication if possible, so when using RAID1/5/6/10 with some devices failed > +and you just added a new device to btrfs using `btrfs-device`(8), you should > +run `btrfs-balance`(8) to rebuild the chunks. > ++ > +See `btrfs-balance`(8) for more details. > + > +Device add/remove/replace:: > +Device can be added/removed using `btrfs-replace`(8) subcommand and replaced > +using `btrfs-replace`(8). > ++ > +When device is removed or replaced, btrfs will do the chunk rebuild if needed. > ++ > +See `btrfs-replace`(8) and this man page for more details. > + > SUBCOMMAND > ---------- > 'add' [-Kf] <dev> [<dev>...] <path>:: > @@ -73,3 +113,5 @@ further details. > SEE ALSO > -------- > `mkfs.btrfs`(8), > +`btrfs-replace`(8), > +`btrfs-balance`(8) > diff --git a/Documentation/btrfs-replace.txt b/Documentation/btrfs-replace.txt > index 8c5dcc4..15a46c2 100644 > --- a/Documentation/btrfs-replace.txt > +++ b/Documentation/btrfs-replace.txt > @@ -13,6 +13,9 @@ DESCRIPTION > ----------- > 'btrfs replace' is used to replace btrfs managed devices with other device. > > +It is recommended to see `btrfs-device`(8) for more details about btrfs device > +management. > + > SUBCOMMAND > ---------- > 'start' [-Bfr] <srcdev>|<devid> <targetdev> <path>:: > @@ -74,3 +77,4 @@ further details. > SEE ALSO > -------- > `mkfs.btrfs`(8), > +`btrfs-device`(8), > -- > 1.9.2 > > -- > To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in > the body of a message to majordomo@vger.kernel.org > More majordomo info at http://vger.kernel.org/majordomo-info.html -- To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Fri, Apr 11, 2014 at 05:16:22PM +0800, Liu Bo wrote: > > +DEVICE MANAGEMENT > > +----------------- > > +Btrfs filesystem is capable to manage multiple devices. > > + > > +Btrfs filesystem use different profiles to manage different RAID level, and > > +use balance to rebuild chunks, also devices can be added/removed/replace > > +online. > > s/use/uses/g > > > + > > +Profile:: > > +Btrfs filesystem use data/metadata profiles to manage allocation/duplication > > +mechanism. Profiles like RAID level can be assigned to data and metadata separately. > > ditto. Both fixed at commit time. Thanks. -- To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Thu, Apr 10, 2014 at 11:10:48PM -0700, Marc MERLIN wrote: > > --- a/Documentation/btrfs-replace.txt > > +++ b/Documentation/btrfs-replace.txt > > @@ -13,6 +13,9 @@ DESCRIPTION > > ----------- > > 'btrfs replace' is used to replace btrfs managed devices with other device. > > I would add a quick line here saying that it's not currently supported for > RAID5/6, and to see btrfs-device for add/delete to get around the replace > missing problem. I've added the quick note when committing the patch. -- To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Fri, Apr 11, 2014 at 07:36:28PM +0200, David Sterba wrote: > On Thu, Apr 10, 2014 at 11:10:48PM -0700, Marc MERLIN wrote: > > > --- a/Documentation/btrfs-replace.txt > > > +++ b/Documentation/btrfs-replace.txt > > > @@ -13,6 +13,9 @@ DESCRIPTION > > > ----------- > > > 'btrfs replace' is used to replace btrfs managed devices with other device. > > > > I would add a quick line here saying that it's not currently supported for > > RAID5/6, and to see btrfs-device for add/delete to get around the replace > > missing problem. > > I've added the quick note when committing the patch. Thanks both. Generally, would you agree to putting more links to the wiki in man pages since man pages are not forever but sure take a long time to update on the installed based and the wiki can be up to date for everyone right away? (I'm not saying to remove info from the man pages, but more something like "btrfs is changing quickly, more up to date information can be found on the wiki page for raid56: https://btrfs.wiki.kernel.org/index.php/RAID56 or btrfsck: https://btrfs.wiki.kernel.org/index.php/Btrfsck btrfs restore: https://btrfs.wiki.kernel.org/index.php/Restore Thanks, Marc
Thanks for fixing the problems. Qu -------- Original Message -------- Subject: Re: [PATCH 1/2] btrfs-progs: Add device management related paragraph. From: David Sterba <dsterba@suse.cz> To: Liu Bo <bo.li.liu@oracle.com> Date: 2014?04?12? 01:34 > On Fri, Apr 11, 2014 at 05:16:22PM +0800, Liu Bo wrote: >>> +DEVICE MANAGEMENT >>> +----------------- >>> +Btrfs filesystem is capable to manage multiple devices. >>> + >>> +Btrfs filesystem use different profiles to manage different RAID level, and >>> +use balance to rebuild chunks, also devices can be added/removed/replace >>> +online. >> s/use/uses/g >> >>> + >>> +Profile:: >>> +Btrfs filesystem use data/metadata profiles to manage allocation/duplication >>> +mechanism. Profiles like RAID level can be assigned to data and metadata separately. >> ditto. > Both fixed at commit time. > > Thanks. -- To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
-------- Original Message -------- Subject: Re: [PATCH 1/2] btrfs-progs: Add device management related paragraph. From: Marc MERLIN <marc@merlins.org> To: dsterba@suse.cz, Qu Wenruo <quwenruo@cn.fujitsu.com>, linux-btrfs@vger.kernel.org Date: 2014?04?12? 01:52 > On Fri, Apr 11, 2014 at 07:36:28PM +0200, David Sterba wrote: >> On Thu, Apr 10, 2014 at 11:10:48PM -0700, Marc MERLIN wrote: >>>> --- a/Documentation/btrfs-replace.txt >>>> +++ b/Documentation/btrfs-replace.txt >>>> @@ -13,6 +13,9 @@ DESCRIPTION >>>> ----------- >>>> 'btrfs replace' is used to replace btrfs managed devices with other device. >>> I would add a quick line here saying that it's not currently supported for >>> RAID5/6, and to see btrfs-device for add/delete to get around the replace >>> missing problem. >> I've added the quick note when committing the patch. > Thanks both. > > Generally, would you agree to putting more links to the wiki in man pages > since man pages are not forever but sure take a long time to update on the > installed based and the wiki can be up to date for everyone right away? > (I'm not saying to remove info from the man pages, but more something like > "btrfs is changing quickly, more up to date information can be found on the > wiki page for > raid56: https://btrfs.wiki.kernel.org/index.php/RAID56 > or > btrfsck: https://btrfs.wiki.kernel.org/index.php/Btrfsck > btrfs restore: https://btrfs.wiki.kernel.org/index.php/Restore > > Thanks, > Marc That's pretty nice and helpful. But one of my concern is that wiki changes are not shown as patches in mail list and somewhat independent from btrfs-progs, so if some developers changed the behavior of RAID56/btrfsck/restore, he or she may only modify the man page but not wiki page. Any good idea to synchronise wiki pages and man pages? Thanks, Qu -- To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Mon, Apr 14, 2014 at 09:16:44AM +0800, Qu Wenruo wrote: > >Generally, would you agree to putting more links to the wiki in man pages > >since man pages are not forever but sure take a long time to update on the > >installed based and the wiki can be up to date for everyone right away? > >(I'm not saying to remove info from the man pages, but more something like > >"btrfs is changing quickly, more up to date information can be found on the > >wiki page for > >raid56: https://btrfs.wiki.kernel.org/index.php/RAID56 > >or > >btrfsck: https://btrfs.wiki.kernel.org/index.php/Btrfsck > >btrfs restore: https://btrfs.wiki.kernel.org/index.php/Restore > > > >Thanks, > >Marc > That's pretty nice and helpful. > But one of my concern is that wiki changes are not shown as patches in > mail list and somewhat > independent from btrfs-progs, > so if some developers changed the behavior of RAID56/btrfsck/restore, he > or she may only modify the man page > but not wiki page. > > Any good idea to synchronise wiki pages and man pages? You raise a good question. I think the wiki should not be there to list all the options that are in the man page. As a result, the wiki should not get out of sync with man pages. The wiki can explain how to use the tools, like some of the pages I listed above, or this page http://marc.merlins.org/perso/btrfs/2014-03.html#Btrfs-Tips_-Btrfs-Scrub-and-Btrfs-Filesystem-Repair A page like this explains what your options are, and what it recommended including links to other resources. Man pages are more "these are the options to use this specific program". In turn the man page cannot be very long and explain all the scenario or explain how this tools works with other tools, so it can point to the wiki that has HOWTOs. So to answer your question, I would say that the man pages should indeed be updated as the programs/binaries get updated, whereas the wiki pages can get updated as needed and refer to bugs in the kernel, or missing features, or features that just got added/improved in kwere kernels. And also like in the page above, generally give an overview of parts of btrfs. Does that make sense? Marc
-------- Original Message -------- Subject: Re: wiki vs man pages From: Marc MERLIN <marc@merlins.org> To: Qu Wenruo <quwenruo@cn.fujitsu.com> Date: 2014?04?14? 09:45 > On Mon, Apr 14, 2014 at 09:16:44AM +0800, Qu Wenruo wrote: >>> Generally, would you agree to putting more links to the wiki in man pages >>> since man pages are not forever but sure take a long time to update on the >>> installed based and the wiki can be up to date for everyone right away? >>> (I'm not saying to remove info from the man pages, but more something like >>> "btrfs is changing quickly, more up to date information can be found on the >>> wiki page for >>> raid56: https://btrfs.wiki.kernel.org/index.php/RAID56 >>> or >>> btrfsck: https://btrfs.wiki.kernel.org/index.php/Btrfsck >>> btrfs restore: https://btrfs.wiki.kernel.org/index.php/Restore >>> >>> Thanks, >>> Marc >> That's pretty nice and helpful. >> But one of my concern is that wiki changes are not shown as patches in >> mail list and somewhat >> independent from btrfs-progs, >> so if some developers changed the behavior of RAID56/btrfsck/restore, he >> or she may only modify the man page >> but not wiki page. >> >> Any good idea to synchronise wiki pages and man pages? > You raise a good question. > > I think the wiki should not be there to list all the options that are in the > man page. As a result, the wiki should not get out of sync with man pages. > > The wiki can explain how to use the tools, like some of the pages I listed > above, or this page > http://marc.merlins.org/perso/btrfs/2014-03.html#Btrfs-Tips_-Btrfs-Scrub-and-Btrfs-Filesystem-Repair > > A page like this explains what your options are, and what it recommended > including links to other resources. > Man pages are more "these are the options to use this specific program". > In turn the man page cannot be very long and explain all the scenario or > explain how this tools works with other tools, so it can point to the wiki > that has HOWTOs. > > So to answer your question, I would say that the man pages should indeed be > updated as the programs/binaries get updated, whereas the wiki pages can get > updated as needed and refer to bugs in the kernel, or missing features, or > features that just got added/improved in kwere kernels. > And also like in the page above, generally give an overview of parts of > btrfs. > > Does that make sense? > > Marc Thanks for your explanation, as for short, man page is showing specifications and wiki explain more use cases/internal mechanism things. I'll add the links to the man pages. Thanks, Qu -- To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
diff --git a/Documentation/btrfs-balance.txt b/Documentation/btrfs-balance.txt index 2289fdf..1b1861c 100644 --- a/Documentation/btrfs-balance.txt +++ b/Documentation/btrfs-balance.txt @@ -14,6 +14,8 @@ DESCRIPTION 'btrfs balance' is used to balance chunks in a btrfs filesystem across multiple or even single device. +See `btrfs-device`(8) for more details about the effect on device management. + SUBCOMMAND ---------- <path>:: @@ -75,3 +77,4 @@ further details. SEE ALSO -------- `mkfs.btrfs`(8), +`btrfs-device`(8) diff --git a/Documentation/btrfs-device.txt b/Documentation/btrfs-device.txt index 20d7bcd..474d411 100644 --- a/Documentation/btrfs-device.txt +++ b/Documentation/btrfs-device.txt @@ -14,6 +14,46 @@ DESCRIPTION 'btrfs device' is used to control the btrfs devices, since btrfs can be used across several devices, 'btrfs device' is used for multiple device management. +DEVICE MANAGEMENT +----------------- +Btrfs filesystem is capable to manage multiple devices. + +Btrfs filesystem use different profiles to manage different RAID level, and +use balance to rebuild chunks, also devices can be added/removed/replace +online. + +Profile:: +Btrfs filesystem use data/metadata profiles to manage allocation/duplication +mechanism. Profiles like RAID level can be assigned to data and metadata separately. ++ +See `mkfs.btrfs`(8) for more details. + +RAID level:: +Btrfs filesystem supports most of the standard RAID level: 0/1/5/6/10. +RAID levels can be assigned at mkfs time or online. ++ +See `mkfs.btrfs`(8) for mkfs time RAID level assign and `btrfs-balance`(8) for +online RAID level assign. + +Balance:: +`btrfs-balance`(8) subcommand can be used to balance or rebuild chunks to the +desired profile. ++ +Due to the fact that balance can rebuild/recovery chunks according to its RAID +duplication if possible, so when using RAID1/5/6/10 with some devices failed +and you just added a new device to btrfs using `btrfs-device`(8), you should +run `btrfs-balance`(8) to rebuild the chunks. ++ +See `btrfs-balance`(8) for more details. + +Device add/remove/replace:: +Device can be added/removed using `btrfs-replace`(8) subcommand and replaced +using `btrfs-replace`(8). ++ +When device is removed or replaced, btrfs will do the chunk rebuild if needed. ++ +See `btrfs-replace`(8) and this man page for more details. + SUBCOMMAND ---------- 'add' [-Kf] <dev> [<dev>...] <path>:: @@ -73,3 +113,5 @@ further details. SEE ALSO -------- `mkfs.btrfs`(8), +`btrfs-replace`(8), +`btrfs-balance`(8) diff --git a/Documentation/btrfs-replace.txt b/Documentation/btrfs-replace.txt index 8c5dcc4..15a46c2 100644 --- a/Documentation/btrfs-replace.txt +++ b/Documentation/btrfs-replace.txt @@ -13,6 +13,9 @@ DESCRIPTION ----------- 'btrfs replace' is used to replace btrfs managed devices with other device. +It is recommended to see `btrfs-device`(8) for more details about btrfs device +management. + SUBCOMMAND ---------- 'start' [-Bfr] <srcdev>|<devid> <targetdev> <path>:: @@ -74,3 +77,4 @@ further details. SEE ALSO -------- `mkfs.btrfs`(8), +`btrfs-device`(8),
Add device management related paragraph to better explain btrfs device management. Cc: Marc MERLIN <marc@merlins.org> Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com> --- Documentation/btrfs-balance.txt | 3 +++ Documentation/btrfs-device.txt | 42 +++++++++++++++++++++++++++++++++++++++++ Documentation/btrfs-replace.txt | 4 ++++ 3 files changed, 49 insertions(+)