[24/27] btrfs-progs: Convert man page for btrfs-zero-log
diff mbox

Message ID 1396427378-10487-25-git-send-email-quwenruo@cn.fujitsu.com
State Accepted
Delegated to: David Sterba
Headers show

Commit Message

Qu Wenruo April 2, 2014, 8:29 a.m. UTC
Convert man page for btrfs-zero-log

Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
---
 Documentation/Makefile           |  2 +-
 Documentation/btrfs-zero-log.txt | 39 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/btrfs-zero-log.txt

Comments

Marc MERLIN April 4, 2014, 6:46 p.m. UTC | #1
On Wed, Apr 02, 2014 at 04:29:35PM +0800, Qu Wenruo wrote:
> Convert man page for btrfs-zero-log
> 
> Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
> ---
>  Documentation/Makefile           |  2 +-
>  Documentation/btrfs-zero-log.txt | 39 +++++++++++++++++++++++++++++++++++++++
>  2 files changed, 40 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/btrfs-zero-log.txt
> 
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index e002d53..de06629 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -11,7 +11,7 @@ MAN8_TXT += btrfs-image.txt
>  MAN8_TXT += btrfs-map-logical.txt
>  MAN8_TXT += btrfs-show-super.txt
>  MAN8_TXT += btrfstune.txt
> -#MAN8_TXT += btrfs-zero-log.txt
> +MAN8_TXT += btrfs-zero-log.txt
>  #MAN8_TXT += fsck.btrfs.txt
>  #MAN8_TXT += mkfs.btrfs.txt
>  
> diff --git a/Documentation/btrfs-zero-log.txt b/Documentation/btrfs-zero-log.txt
> new file mode 100644
> index 0000000..e3041fa
> --- /dev/null
> +++ b/Documentation/btrfs-zero-log.txt
> @@ -0,0 +1,39 @@
> +btrfs-zero-log(8)
> +=================
> +
> +NAME
> +----
> +btrfs-zero-log - clear out log tree
> +
> +SYNOPSIS
> +--------
> +'btrfs-zero-log' <dev>
> +
> +DESCRIPTION
> +-----------
> +'btrfs-zero-log' will remove the log tree if log tree is corrupt, which will
> +allow you to mount the filesystem again.
> +
> +The common case where this happens has been fixed a long time ago,
> +so it is unlikely that you will see this particular problem.

A note on this one: this can happen if your SSD rites things in the
wrong order or potentially writes garbage when power is lost, or before
locking up.
I hit this problem about 10 times and it wasn't a btrfs bug, just the
drive doing bad things.

I had debian add this to the initramfs initrd by default so that someone
can recover their root filesystem with this command if it won't mount.

What got fixed is the kernel used to oops and crash, and now it gives a
nice "can't mount" error message.

Marc
cwillu April 5, 2014, 10 p.m. UTC | #2
On Fri, Apr 4, 2014 at 12:46 PM, Marc MERLIN <marc@merlins.org> wrote:
> On Wed, Apr 02, 2014 at 04:29:35PM +0800, Qu Wenruo wrote:
>> Convert man page for btrfs-zero-log
>>
>> Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
>> ---
>>  Documentation/Makefile           |  2 +-
>>  Documentation/btrfs-zero-log.txt | 39 +++++++++++++++++++++++++++++++++++++++
>>  2 files changed, 40 insertions(+), 1 deletion(-)
>>  create mode 100644 Documentation/btrfs-zero-log.txt
>>
>> diff --git a/Documentation/Makefile b/Documentation/Makefile
>> index e002d53..de06629 100644
>> --- a/Documentation/Makefile
>> +++ b/Documentation/Makefile
>> @@ -11,7 +11,7 @@ MAN8_TXT += btrfs-image.txt
>>  MAN8_TXT += btrfs-map-logical.txt
>>  MAN8_TXT += btrfs-show-super.txt
>>  MAN8_TXT += btrfstune.txt
>> -#MAN8_TXT += btrfs-zero-log.txt
>> +MAN8_TXT += btrfs-zero-log.txt
>>  #MAN8_TXT += fsck.btrfs.txt
>>  #MAN8_TXT += mkfs.btrfs.txt
>>
>> diff --git a/Documentation/btrfs-zero-log.txt b/Documentation/btrfs-zero-log.txt
>> new file mode 100644
>> index 0000000..e3041fa
>> --- /dev/null
>> +++ b/Documentation/btrfs-zero-log.txt
>> @@ -0,0 +1,39 @@
>> +btrfs-zero-log(8)
>> +=================
>> +
>> +NAME
>> +----
>> +btrfs-zero-log - clear out log tree
>> +
>> +SYNOPSIS
>> +--------
>> +'btrfs-zero-log' <dev>
>> +
>> +DESCRIPTION
>> +-----------
>> +'btrfs-zero-log' will remove the log tree if log tree is corrupt, which will
>> +allow you to mount the filesystem again.
>> +
>> +The common case where this happens has been fixed a long time ago,
>> +so it is unlikely that you will see this particular problem.
>
> A note on this one: this can happen if your SSD rites things in the
> wrong order or potentially writes garbage when power is lost, or before
> locking up.
> I hit this problem about 10 times and it wasn't a btrfs bug, just the
> drive doing bad things.

And -o recovery didn't work around it?  My understanding is that -o
recovery will skip reading the log.
--
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
Marc MERLIN April 5, 2014, 10:02 p.m. UTC | #3
On Sat, Apr 05, 2014 at 04:00:27PM -0600, cwillu wrote:
> >> +'btrfs-zero-log' will remove the log tree if log tree is corrupt, which will
> >> +allow you to mount the filesystem again.
> >> +
> >> +The common case where this happens has been fixed a long time ago,
> >> +so it is unlikely that you will see this particular problem.
> >
> > A note on this one: this can happen if your SSD rites things in the
> > wrong order or potentially writes garbage when power is lost, or before
> > locking up.
> > I hit this problem about 10 times and it wasn't a btrfs bug, just the
> > drive doing bad things.
> 
> And -o recovery didn't work around it?  My understanding is that -o
> recovery will skip reading the log.

Maybe it does, but if you're trying to mount your root filesystem to boot
your laptop, that's not super useful since -o recovery is indeed a read only
recovery mode.
btrfs-zero-log just cleans the last log entry and gave me back a fully working
read/write filesystem each time.

Marc
Hugo Mills April 5, 2014, 10:02 p.m. UTC | #4
On Sat, Apr 05, 2014 at 04:00:27PM -0600, cwillu wrote:
> On Fri, Apr 4, 2014 at 12:46 PM, Marc MERLIN <marc@merlins.org> wrote:
> > On Wed, Apr 02, 2014 at 04:29:35PM +0800, Qu Wenruo wrote:
> >> Convert man page for btrfs-zero-log
> >>
> >> Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
> >> ---
> >>  Documentation/Makefile           |  2 +-
> >>  Documentation/btrfs-zero-log.txt | 39 +++++++++++++++++++++++++++++++++++++++
> >>  2 files changed, 40 insertions(+), 1 deletion(-)
> >>  create mode 100644 Documentation/btrfs-zero-log.txt
> >>
> >> diff --git a/Documentation/Makefile b/Documentation/Makefile
> >> index e002d53..de06629 100644
> >> --- a/Documentation/Makefile
> >> +++ b/Documentation/Makefile
> >> @@ -11,7 +11,7 @@ MAN8_TXT += btrfs-image.txt
> >>  MAN8_TXT += btrfs-map-logical.txt
> >>  MAN8_TXT += btrfs-show-super.txt
> >>  MAN8_TXT += btrfstune.txt
> >> -#MAN8_TXT += btrfs-zero-log.txt
> >> +MAN8_TXT += btrfs-zero-log.txt
> >>  #MAN8_TXT += fsck.btrfs.txt
> >>  #MAN8_TXT += mkfs.btrfs.txt
> >>
> >> diff --git a/Documentation/btrfs-zero-log.txt b/Documentation/btrfs-zero-log.txt
> >> new file mode 100644
> >> index 0000000..e3041fa
> >> --- /dev/null
> >> +++ b/Documentation/btrfs-zero-log.txt
> >> @@ -0,0 +1,39 @@
> >> +btrfs-zero-log(8)
> >> +=================
> >> +
> >> +NAME
> >> +----
> >> +btrfs-zero-log - clear out log tree
> >> +
> >> +SYNOPSIS
> >> +--------
> >> +'btrfs-zero-log' <dev>
> >> +
> >> +DESCRIPTION
> >> +-----------
> >> +'btrfs-zero-log' will remove the log tree if log tree is corrupt, which will
> >> +allow you to mount the filesystem again.
> >> +
> >> +The common case where this happens has been fixed a long time ago,
> >> +so it is unlikely that you will see this particular problem.
> >
> > A note on this one: this can happen if your SSD rites things in the
> > wrong order or potentially writes garbage when power is lost, or before
> > locking up.
> > I hit this problem about 10 times and it wasn't a btrfs bug, just the
> > drive doing bad things.
> 
> And -o recovery didn't work around it?  My understanding is that -o
> recovery will skip reading the log.

   No, I'm pretty sure we've had people with problems with the log
where -orecovery didn't help, but -oro,recovery allowed it to be
mounted, because -ro didn't try to replay the log.

   Hugo.
Hugo Mills April 5, 2014, 10:03 p.m. UTC | #5
On Sat, Apr 05, 2014 at 03:02:03PM -0700, Marc MERLIN wrote:
> On Sat, Apr 05, 2014 at 04:00:27PM -0600, cwillu wrote:
> > >> +'btrfs-zero-log' will remove the log tree if log tree is corrupt, which will
> > >> +allow you to mount the filesystem again.
> > >> +
> > >> +The common case where this happens has been fixed a long time ago,
> > >> +so it is unlikely that you will see this particular problem.
> > >
> > > A note on this one: this can happen if your SSD rites things in the
> > > wrong order or potentially writes garbage when power is lost, or before
> > > locking up.
> > > I hit this problem about 10 times and it wasn't a btrfs bug, just the
> > > drive doing bad things.
> > 
> > And -o recovery didn't work around it?  My understanding is that -o
> > recovery will skip reading the log.
> 
> Maybe it does, but if you're trying to mount your root filesystem to boot
> your laptop, that's not super useful since -o recovery is indeed a read only
> recovery mode.
> btrfs-zero-log just cleans the last log entry and gave me back a fully working
> read/write filesystem each time.

   As far as I recall, -orecovery is read-write. -oro,recovery is
read-only.

   Hugo.
Marc MERLIN April 5, 2014, 10:05 p.m. UTC | #6
On Sat, Apr 05, 2014 at 03:02:03PM -0700, Marc MERLIN wrote:
> On Sat, Apr 05, 2014 at 04:00:27PM -0600, cwillu wrote:
> > >> +'btrfs-zero-log' will remove the log tree if log tree is corrupt, which will
> > >> +allow you to mount the filesystem again.
> > >> +
> > >> +The common case where this happens has been fixed a long time ago,
> > >> +so it is unlikely that you will see this particular problem.
> > >
> > > A note on this one: this can happen if your SSD rites things in the
> > > wrong order or potentially writes garbage when power is lost, or before
> > > locking up.
> > > I hit this problem about 10 times and it wasn't a btrfs bug, just the
> > > drive doing bad things.
> > 
> > And -o recovery didn't work around it?  My understanding is that -o
> > recovery will skip reading the log.
> 
> Maybe it does, but if you're trying to mount your root filesystem to boot
> your laptop, that's not super useful since -o recovery is indeed a read only
> recovery mode.

Sorry, -o recovery is not read only, but -o recovery,ro which is usually
what is needed for things to work in my experience, is indeed read only.

Marc
Marc MERLIN April 5, 2014, 10:21 p.m. UTC | #7
On Sat, Apr 05, 2014 at 11:03:46PM +0100, Hugo Mills wrote:
>    As far as I recall, -orecovery is read-write. -oro,recovery is
> read-only.

Yes, we both corrected my Email at the same time :)

Actually it's better/worse than that. From my notes at
http://marc.merlins.org/perso/btrfs/2014-03.html#Btrfs-Tips_-Btrfs-Scrub-and-Btrfs-Filesystem-Repair

mount -o recovery,ro (for when regular mount isn't working). Note, you have to use ro or it will give you a misleading error:
root@polgara:~# mount -o recovery /dev/mapper/crypt /mnt/mnt8
mount: /dev/mapper/crypt already mounted or /mnt/mnt8 busy
root@polgara:~# mount -o recovery,ro /dev/mapper/crypt /mnt/mnt8
root@polgara:~#

In other words, for me -o recovery has never worked unless I added ,ro.
I'm not saying -o recovery cannot work, but when I needed it, it didn't work
because likely it failed to replay the log as you say, and adding ro fixed
that problem.

That said, returning
mount: /dev/mapper/crypt already mounted or /mnt/mnt8 busy                                                                                
is not ideal :)

Marc
Qu Wenruo April 8, 2014, 1:42 a.m. UTC | #8
? 2014?04?05? 02:46, Marc MERLIN ??:
> On Wed, Apr 02, 2014 at 04:29:35PM +0800, Qu Wenruo wrote:
>> Convert man page for btrfs-zero-log
>>
>> Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
>> ---
>>   Documentation/Makefile           |  2 +-
>>   Documentation/btrfs-zero-log.txt | 39 +++++++++++++++++++++++++++++++++++++++
>>   2 files changed, 40 insertions(+), 1 deletion(-)
>>   create mode 100644 Documentation/btrfs-zero-log.txt
>>
>> diff --git a/Documentation/Makefile b/Documentation/Makefile
>> index e002d53..de06629 100644
>> --- a/Documentation/Makefile
>> +++ b/Documentation/Makefile
>> @@ -11,7 +11,7 @@ MAN8_TXT += btrfs-image.txt
>>   MAN8_TXT += btrfs-map-logical.txt
>>   MAN8_TXT += btrfs-show-super.txt
>>   MAN8_TXT += btrfstune.txt
>> -#MAN8_TXT += btrfs-zero-log.txt
>> +MAN8_TXT += btrfs-zero-log.txt
>>   #MAN8_TXT += fsck.btrfs.txt
>>   #MAN8_TXT += mkfs.btrfs.txt
>>   
>> diff --git a/Documentation/btrfs-zero-log.txt b/Documentation/btrfs-zero-log.txt
>> new file mode 100644
>> index 0000000..e3041fa
>> --- /dev/null
>> +++ b/Documentation/btrfs-zero-log.txt
>> @@ -0,0 +1,39 @@
>> +btrfs-zero-log(8)
>> +=================
>> +
>> +NAME
>> +----
>> +btrfs-zero-log - clear out log tree
>> +
>> +SYNOPSIS
>> +--------
>> +'btrfs-zero-log' <dev>
>> +
>> +DESCRIPTION
>> +-----------
>> +'btrfs-zero-log' will remove the log tree if log tree is corrupt, which will
>> +allow you to mount the filesystem again.
>> +
>> +The common case where this happens has been fixed a long time ago,
>> +so it is unlikely that you will see this particular problem.
> A note on this one: this can happen if your SSD rites things in the
> wrong order or potentially writes garbage when power is lost, or before
> locking up.
> I hit this problem about 10 times and it wasn't a btrfs bug, just the
> drive doing bad things.
>
> I had debian add this to the initramfs initrd by default so that someone
> can recover their root filesystem with this command if it won't mount.
>
> What got fixed is the kernel used to oops and crash, and now it gives a
> nice "can't mount" error message.
>
> Marc
Thanks for the note.

After reading following up mails on the thread, I agree that the note is 
needed.

But I would like to add more method to judge whether to call 
btrfs-zero-log or other tools like btrfsck.

It would be quite nice if any one can provide a log-tree-broken small 
btrfs image for me to test?
(Personally, I would prefer using dmesg warning/backtrace and btrfsck 
result to make sure to call btrfs-zero-log)

P.S: If btrfs can be automatically mounted as RO when log tree is 
broken, it would be better.
But it also seems log tree related things will be improved sooner or 
later, it may not be so urgent.

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
Marc MERLIN April 11, 2014, 5:54 a.m. UTC | #9
On Tue, Apr 08, 2014 at 09:42:03AM +0800, Qu Wenruo wrote:
> >I had debian add this to the initramfs initrd by default so that someone
> >can recover their root filesystem with this command if it won't mount.
> >
> >What got fixed is the kernel used to oops and crash, and now it gives a
> >nice "can't mount" error message.
> >
> >Marc
> Thanks for the note.
> 
> After reading following up mails on the thread, I agree that the note is 
> needed.
> 
> But I would like to add more method to judge whether to call 
> btrfs-zero-log or other tools like btrfsck.
 
Sounds like a good idea. It may also make sense in places to have the man
page point to the btrfs wiki for more detailled info since it's easier to
update the wiki than to update the man page on thousands or millions of
systems :)

I wrote 
http://marc.merlins.org/perso/btrfs/2014-03.html#Btrfs-Tips_-Btrfs-Scrub-and-Btrfs-Filesystem-Repair
which is linked off
https://btrfs.wiki.kernel.org/index.php/Btrfsck
which I just updated with more details.

It would be great to put a pointer to the official wiki in the man page, and
also in the btrfsck man page which currently doesn't warn people enough that
they have many other options to try before btrfsck.

Now that I updated the official wiki page, would you agree that it would be
good to link to it in the man page?

> It would be quite nice if any one can provide a log-tree-broken small 
> btrfs image for me to test?
> (Personally, I would prefer using dmesg warning/backtrace and btrfsck 
> result to make sure to call btrfs-zero-log)

Unfortunately, my broken SSD that was generating that corruption has been
returned to the vendor, and my new SSD doesn't crash anymore, so I don't
have such broken filesystem anymore.
 
> P.S: If btrfs can be automatically mounted as RO when log tree is 
> broken, it would be better.
> But it also seems log tree related things will be improved sooner or 
> later, it may not be so urgent.

I agree this is a great idea, especially if it's the root filesystem without
which you can't fix the machine that's broken.

Thank you,
Marc

Patch
diff mbox

diff --git a/Documentation/Makefile b/Documentation/Makefile
index e002d53..de06629 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -11,7 +11,7 @@  MAN8_TXT += btrfs-image.txt
 MAN8_TXT += btrfs-map-logical.txt
 MAN8_TXT += btrfs-show-super.txt
 MAN8_TXT += btrfstune.txt
-#MAN8_TXT += btrfs-zero-log.txt
+MAN8_TXT += btrfs-zero-log.txt
 #MAN8_TXT += fsck.btrfs.txt
 #MAN8_TXT += mkfs.btrfs.txt
 
diff --git a/Documentation/btrfs-zero-log.txt b/Documentation/btrfs-zero-log.txt
new file mode 100644
index 0000000..e3041fa
--- /dev/null
+++ b/Documentation/btrfs-zero-log.txt
@@ -0,0 +1,39 @@ 
+btrfs-zero-log(8)
+=================
+
+NAME
+----
+btrfs-zero-log - clear out log tree
+
+SYNOPSIS
+--------
+'btrfs-zero-log' <dev>
+
+DESCRIPTION
+-----------
+'btrfs-zero-log' will remove the log tree if log tree is corrupt, which will
+allow you to mount the filesystem again.
+
+The common case where this happens has been fixed a long time ago,
+so it is unlikely that you will see this particular problem.
+
+EXIT STATUS
+-----------
+'btrfs-zero-log' will return 0 if no error happened.
+Other exit code means some problems happened.
+
+AUTHOR
+------
+Written by Shilong Wang and Wenruo Qu.
+
+COPYRIGHT
+---------
+Copyright (C) 2013 FUJITSU LIMITED.
+
+License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
+
+This is free software: you are free  to  change  and  redistribute  it. There is NO WARRANTY, to the extent permitted by law.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8)