.\" Copyright (c) 2006-2009 Pawel Jakub Dawidek <pjd@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd February 17, 2009
.Dt GJOURNAL 8
.Os
.Sh NAME
.Nm gjournal
.Nd "control utility for journaled devices"
.Sh SYNOPSIS
.Nm
.Cm label
.Op Fl cfhv
.Op Fl s Ar jsize
.Ar dataprov
.Op Ar jprov
.Nm
.Cm stop
.Op Fl fv
.Ar name ...
.Nm
.Cm sync
.Op Fl v
.Nm
.Cm clear
.Op Fl v
.Ar prov ...
.Nm
.Cm dump
.Ar prov ...
.Nm
.Cm list
.Nm
.Cm status
.Nm
.Cm load
.Nm
.Cm unload
.Sh DESCRIPTION
The
.Nm
utility is used for journal configuration on the given GEOM provider.
The Journal and data may be stored on the same provider or on two separate
providers.
This is block level journaling, not file system level journaling, which means
everything gets logged, e.g.\& for file systems, it journals both data and
metadata.
The
.Nm
GEOM class can talk to file systems, which allows the use of
.Nm
for file system journaling and to keep file systems in a consistent state.
At this time, only UFS file system is supported.
.Pp
To configure journaling on the UFS file system using
.Nm ,
one should first create a
.Nm
provider using the
.Nm
utility, then run
.Xr newfs 8
or
.Xr tunefs 8
on it with the
.Fl J
flag which instructs UFS to cooperate with the
.Nm
provider below.
There are important differences in how journaled UFS works.
The most important one is that
.Xr sync 2
and
.Xr fsync 2
system calls do not work as expected anymore.
To ensure that data is stored on the data provider, the
.Nm Cm sync
command should be used after calling
.Xr sync 2 .
For the best performance possible, soft-updates should be disabled when
.Nm
is used.
It is also safe and recommended to use the
.Cm async
.Xr mount 8
option.
.Pp
When
.Nm
is configured on top of
.Xr gmirror 8
or
.Xr graid3 8
providers, it also keeps them in a consistent state, thus
automatic synchronization on power failure or system crash may be disabled
on those providers.
.Pp
The
.Nm
utility uses on-disk metadata, stored in the provider's last sector,
to store all needed information.
This could be a problem when an existing file system is converted to use
.Nm .
.Pp
The first argument to
.Nm
indicates an action to be performed:
.Bl -tag -width ".Cm status"
.It Cm label
Configures
.Nm
on the given provider(s).
If only one provider is given, both data and journal are stored on the same
provider.
If two providers are given, the first one will be used as data provider and the
second will be used as the journal provider.
.Pp
Additional options include:
.Bl -tag -width ".Fl s Ar jsize"
.It Fl c
Checksum journal records.
.It Fl f
May be used to convert an existing file system to use
.Nm ,
but only if the journal will be configured on a separate provider and if the
last sector in the data provider is not used by the existing file system.
If
.Nm
detects that the last sector is used, it will refuse to overwrite it
and return an error.
This behavior may be forced by using the
.Fl f
flag, which will force
.Nm
to overwrite the last sector.
.It Fl h
Hardcode provider names in metadata.
.It Fl s Ar jsize
Specifies size of the journal if only one provider is used for both data and
journal.
The default is one gigabyte.
Size should be chosen based on provider's load, and not on its size;
recommended minimum is twice the size of the physical memory installed.
It is not recommended to use
.Nm
for small file systems (e.g.: only few gigabytes big).
.El
.It Cm clear
Clear metadata on the given providers.
.It Cm stop
Stop the given provider.
.Pp
Additional options include:
.Bl -tag -width ".Fl f"
.It Fl f
Stop the given provider even if it is opened.
.El
.It Cm sync
Trigger journal switch and enforce sending data to the data provider.
.It Cm dump
Dump metadata stored on the given providers.
.It Cm list
See
.Xr geom 8 .
.It Cm status
See
.Xr geom 8 .
.It Cm load
See
.Xr geom 8 .
.It Cm unload
See
.Xr geom 8 .
.El
.Pp
Additional options include:
.Bl -tag -width ".Fl v"
.It Fl v
Be more verbose.
.El
.Sh EXIT STATUS
Exit status is 0 on success, and 1 if the command fails.
.Sh EXAMPLES
Create a
.Nm
based UFS file system and mount it:
.Bd -literal -offset indent
gjournal load
gjournal label da0
newfs -J /dev/da0.journal
mount -o async /dev/da0.journal /mnt
.Ed
.Pp
Configure journaling on an existing file system, but only if
.Nm
allows this (i.e., if the last sector is not already used by the file system):
.Bd -literal -offset indent
umount /dev/da0s1d
gjournal label da0s1d da0s1e && \e
    tunefs -J enable -n disable da0s1d.journal && \e
    mount -o async /dev/da0s1d.journal /mnt || \e
    mount /dev/da0s1d /mnt
.Ed
.Sh SYSCTLS
Gjournal adds the sysctl level kern.geom.journal.
The string and integer information available is detailed below.
The changeable column shows whether a process with appropriate privilege may
change the value.
.Bl -column "accept_immediatelyXXXXXX" integerXXX -offset indent
.It Sy "sysctl name	Type	Changeable"
.It "debug	integer	yes"
.It "switch_time	integer	yes"
.It "force_switch	integer	yes"
.It "parallel_flushes	integer	yes"
.It "accept_immediately	integer	yes"
.It "parallel_copies	integer	yes"
.It "record_entries	integer	yes"
.It "optimize	integer	yes"
.El
.Bl -tag -width 6n
.It Li debug
Setting a non-zero value enables debugging at various levels.
Debug level 1 will record actions at a journal level, relating to journal
switches, metadata updates, etc.
Debug level 2 will record actions at a higher level, relating to the numbers of
entries in journals, access requests, etc.
Debug level 3 will record verbose detail, including insertion of I/Os to the
journal.
.It Li switch_time
The maximum number of seconds a journal is allowed to remain open before
switching to a new journal.
.It Li force_switch
Force a journal switch when the journal uses more than N% of the free journal
space.
.It Li parallel_flushes
The number of flush I/O requests to be sent in parallel when flushing the
journal to the data provider.
.It Li accept_immediately
The maximum number of I/O requests accepted at the same time.
.It Li parallel_copies
The number of copy I/O requests to send in parallel.
.It Li record_entries
The maximum number of record entries to allow in a single journal.
.It Li optimize
Controls whether entries in a journal will be optimized by combining overlapping
I/Os into a single I/O and reordering the entries in a journal.
This can be disabled by setting the sysctl to 0.
.El
.Ss cache
The string and integer information available for the cache level
is detailed below.
The changeable column shows whether a process with appropriate
privilege may change the value.
.Bl -column "alloc_failuresXXXXXX" integerXXX -offset indent
.It Sy "sysctl name	Type	Changeable"
.It "used	integer	no"
.It "limit	integer	yes"
.It "divisor	integer	no"
.It "switch	integer	yes"
.It "misses	integer	yes"
.It "alloc_failures	integer	yes"
.El
.Bl -tag -width 6n
.It Li used
The number of bytes currently allocated to the cache.
.It Li limit
The maximum number of bytes to be allocated to the cache.
.It Li divisor
Sets the cache size to be used as a proportion of kmem_size.
A value of 2 (the default) will cause the cache size to be set to 1/2 of the
kmem_size.
.It Li switch
Force a journal switch when this percentage of cache has been used.
.It Li misses
The number of cache misses, when data has been read, but was not found in the
cache.
.It Li alloc_failures
The number of times memory failed to be allocated to the cache because the cache
limit was hit.
.El
.Ss stats
The string and integer information available for the statistics level
is detailed below.
The changeable column shows whether a process with appropriate
privilege may change the value.
.Bl -column "skipped_bytesXXXXXX" integerXXX -offset indent
.It Sy "sysctl name	Type	Changeable"
.It "skipped_bytes	integer	yes"
.It "combined_ios	integer	yes"
.It "switches	integer	yes"
.It "wait_for_copy	integer	yes"
.It "journal_full	integer	yes"
.It "low_mem	integer	yes"
.El
.Bl -tag -width 6n
.It Li skipped_bytes
The number of bytes skipped.
.It Li combined_ios
The number of I/Os which were combined by journal optimization.
.It Li switches
The number of journal switches.
.It Li wait_for_copy
The number of times the journal switch process had to wait for the previous
journal copy to complete.
.It Li journal_full
The number of times the journal was almost full, forcing a journal switch.
.It Li low_mem
The number of times the low_mem hook was called.
.El
.Sh SEE ALSO
.Xr geom 4 ,
.Xr geom 8 ,
.Xr mount 8 ,
.Xr newfs 8 ,
.Xr tunefs 8 ,
.Xr umount 8
.Sh HISTORY
The
.Nm
utility appeared in
.Fx 7.0 .
.Sh AUTHORS
.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org