1 .\" Copyright (c) 2006-2009 Pawel Jakub Dawidek <pjd@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .Nd "control utility for journaled devices"
63 utility is used for journal configuration on the given GEOM provider.
64 The Journal and data may be stored on the same provider or on two separate
66 This is block level journaling, not file system level journaling, which means
67 everything gets logged, e.g.\& for file systems, it journals both data and
71 GEOM class can talk to file systems, which allows the use of
73 for file system journaling and to keep file systems in a consistent state.
74 At this time, only UFS file system is supported.
76 To configure journaling on the UFS file system using
78 one should first create a
88 flag which instructs UFS to cooperate with the
91 There are important differences in how journaled UFS works.
92 The most important one is that
96 system calls do not work as expected anymore.
97 To ensure that data is stored on the data provider, the
99 command should be used after calling
101 For the best performance possible, soft-updates should be disabled when
104 It is also safe and recommended to use the
111 is configured on top of
115 providers, it also keeps them in a consistent state, thus
116 automatic synchronization on power failure or system crash may be disabled
121 utility uses on-disk metadata, stored in the provider's last sector,
122 to store all needed information.
123 This could be a problem when an existing file system is converted to use
126 The first argument to
128 indicates an action to be performed:
129 .Bl -tag -width ".Cm status"
133 on the given provider(s).
134 If only one provider is given, both data and journal are stored on the same
136 If two providers are given, the first one will be used as data provider and the
137 second will be used as the journal provider.
139 Additional options include:
140 .Bl -tag -width ".Fl s Ar jsize"
142 Checksum journal records.
144 May be used to convert an existing file system to use
146 but only if the journal will be configured on a separate provider and if the
147 last sector in the data provider is not used by the existing file system.
150 detects that the last sector is used, it will refuse to overwrite it
152 This behavior may be forced by using the
154 flag, which will force
156 to overwrite the last sector.
158 Hardcode provider names in metadata.
160 Specifies size of the journal if only one provider is used for both data and
162 The default is one gigabyte.
163 Size should be chosen based on provider's load, and not on its size;
164 recommended minimum is twice the size of the physical memory installed.
165 It is not recommended to use
167 for small file systems (e.g.: only few gigabytes big).
170 Clear metadata on the given providers.
172 Stop the given provider.
174 Additional options include:
175 .Bl -tag -width ".Fl f"
177 Stop the given provider even if it is opened.
180 Trigger journal switch and enforce sending data to the data provider.
182 Dump metadata stored on the given providers.
197 Additional options include:
198 .Bl -tag -width ".Fl v"
203 Exit status is 0 on success, and 1 if the command fails.
207 based UFS file system and mount it:
208 .Bd -literal -offset indent
211 newfs -J /dev/da0.journal
212 mount -o async /dev/da0.journal /mnt
215 Configure journaling on an existing file system, but only if
217 allows this (i.e., if the last sector is not already used by the file system):
218 .Bd -literal -offset indent
220 gjournal label da0s1d da0s1e && \e
221 tunefs -J enable -n disable da0s1d.journal && \e
222 mount -o async /dev/da0s1d.journal /mnt || \e
223 mount /dev/da0s1d /mnt
226 Gjournal adds the sysctl level kern.geom.journal.
227 The string and integer information available is detailed below.
228 The changeable column shows whether a process with appropriate privilege may
230 .Bl -column "accept_immediatelyXXXXXX" integerXXX -offset indent
231 .It Sy "sysctl name Type Changeable"
232 .It "debug integer yes"
233 .It "switch_time integer yes"
234 .It "force_switch integer yes"
235 .It "parallel_flushes integer yes"
236 .It "accept_immediately integer yes"
237 .It "parallel_copies integer yes"
238 .It "record_entries integer yes"
239 .It "optimize integer yes"
243 Setting a non-zero value enables debugging at various levels.
244 Debug level 1 will record actions at a journal level, relating to journal
245 switches, metadata updates, etc.
246 Debug level 2 will record actions at a higher level, relating to the numbers of
247 entries in journals, access requests, etc.
248 Debug level 3 will record verbose detail, including insertion of I/Os to the
251 The maximum number of seconds a journal is allowed to remain open before
252 switching to a new journal.
254 Force a journal switch when the journal uses more than N% of the free journal
256 .It Li parallel_flushes
257 The number of flush I/O requests to be sent in parallel when flushing the
258 journal to the data provider.
259 .It Li accept_immediately
260 The maximum number of I/O requests accepted at the same time.
261 .It Li parallel_copies
262 The number of copy I/O requests to send in parallel.
263 .It Li record_entries
264 The maximum number of record entries to allow in a single journal.
266 Controls whether entries in a journal will be optimized by combining overlapping
267 I/Os into a single I/O and reordering the entries in a journal.
268 This can be disabled by setting the sysctl to 0.
271 The string and integer information available for the cache level
273 The changeable column shows whether a process with appropriate
274 privilege may change the value.
275 .Bl -column "alloc_failuresXXXXXX" integerXXX -offset indent
276 .It Sy "sysctl name Type Changeable"
277 .It "used integer no"
278 .It "limit integer yes"
279 .It "divisor integer no"
280 .It "switch integer yes"
281 .It "misses integer yes"
282 .It "alloc_failures integer yes"
286 The number of bytes currently allocated to the cache.
288 The maximum number of bytes to be allocated to the cache.
290 Sets the cache size to be used as a proportion of kmem_size.
291 A value of 2 (the default) will cause the cache size to be set to 1/2 of the
294 Force a journal switch when this percentage of cache has been used.
296 The number of cache misses, when data has been read, but was not found in the
298 .It Li alloc_failures
299 The number of times memory failed to be allocated to the cache because the cache
303 The string and integer information available for the statistics level
305 The changeable column shows whether a process with appropriate
306 privilege may change the value.
307 .Bl -column "skipped_bytesXXXXXX" integerXXX -offset indent
308 .It Sy "sysctl name Type Changeable"
309 .It "skipped_bytes integer yes"
310 .It "combined_ios integer yes"
311 .It "switches integer yes"
312 .It "wait_for_copy integer yes"
313 .It "journal_full integer yes"
314 .It "low_mem integer yes"
318 The number of bytes skipped.
320 The number of I/Os which were combined by journal optimization.
322 The number of journal switches.
324 The number of times the journal switch process had to wait for the previous
325 journal copy to complete.
327 The number of times the journal was almost full, forcing a journal switch.
329 The number of times the low_mem hook was called.
344 .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org