Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GJOURNAL(8)		  BSD System Manager's Manual		   GJOURNAL(8)

     gjournal -- control utility for journaled devices

     gjournal label [-cfhv] [-s	jsize] dataprov	[jprov]
     gjournal stop [-fv] name ...
     gjournal sync [-v]
     gjournal clear [-v] prov ...
     gjournal dump prov	...
     gjournal list
     gjournal status
     gjournal load
     gjournal unload

     The gjournal 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 sys-
     tems, it journals both data and metadata.	The gjournal GEOM class	can
     talk to file systems, which allows	the use	of gjournal for	file system
     journaling	and to keep file systems in a consistent state.	 At this time,
     only UFS file system is supported.

     To	configure journaling on	the UFS	file system using gjournal, one	should
     first create a gjournal provider using the	gjournal utility, then run
     newfs(8) or tunefs(8) on it with the -J flag which	instructs UFS to coop-
     erate with	the gjournal provider below.  There are	important differences
     in	how journaled UFS works.  The most important one is that sync(2) and
     fsync(2) system calls do not work as expected anymore.  To	ensure that
     data is stored on the data	provider, the gjournal sync command should be
     used after	calling	sync(2).  For the best performance possible, soft-up-
     dates should be disabled when gjournal is used.  It is also safe and rec-
     ommended to use the async mount(8)	option.

     When gjournal is configured on top	of gmirror(8) or 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.

     The gjournal 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 gjournal.

     The first argument	to gjournal indicates an action	to be performed:

     label   Configures	gjournal 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

	     Additional	options	include:

	     -c	       Checksum	journal	records.

	     -f	       May be used to convert an existing file system to use
		       gjournal, 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
		       gjournal	detects	that the last sector is	used, it will
		       refuse to overwrite it and return an error.  This be-
		       havior may be forced by using the -f flag, which	will
		       force gjournal to overwrite the last sector.

	     -h	       Hardcode	provider names in metadata.

	     -s	jsize  Specifies size of the journal if	only one provider is
		       used for	both data and journal.	The default is one gi-
		       gabyte.	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 gjournal for small file systems
		       (e.g.: only few gigabytes big).

     clear   Clear metadata on the given providers.

     stop    Stop the given provider.

	     Additional	options	include:

	     -f	 Stop the given	provider even if it is opened.

     sync    Trigger journal switch and	enforce	sending	data to	the data

     dump    Dump metadata stored on the given providers.

     list    See geom(8).

     status  See geom(8).

     load    See geom(8).

     unload  See geom(8).

     Additional	options	include:

     -v	 Be more verbose.

     Exit status is 0 on success, and 1	if the command fails.

     Create a gjournal based UFS file system and mount it:

	   gjournal load
	   gjournal label da0
	   newfs -J /dev/da0.journal
	   mount -o async /dev/da0.journal /mnt

     Configure journaling on an	existing file system, but only if gjournal al-
     lows this (i.e., if the last sector is not	already	used by	the file sys-

	   umount /dev/da0s1d
	   gjournal label da0s1d da0s1e	&& \
	       tunefs -J enable	-n disable da0s1d.journal && \
	       mount -o	async /dev/da0s1d.journal /mnt || \
	       mount /dev/da0s1d /mnt

     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.

	   sysctl name		       Type	     Changeable
	   debug		       integer	     yes
	   switch_time		       integer	     yes
	   force_switch		       integer	     yes
	   parallel_flushes	       integer	     yes
	   accept_immediately	       integer	     yes
	   parallel_copies	       integer	     yes
	   record_entries	       integer	     yes
	   optimize		       integer	     yes

     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 en-
	     tries in journals,	access requests, etc.  Debug level 3 will
	     record verbose detail, including insertion	of I/Os	to the jour-

	     The maximum number	of seconds a journal is	allowed	to remain open
	     before switching to a new journal.

	     Force a journal switch when the journal uses more than N% of the
	     free journal space.

	     The number	of flush I/O requests to be sent in parallel when
	     flushing the journal to the data provider.

	     The maximum number	of I/O requests	accepted at the	same time.

	     The number	of copy	I/O requests to	send in	parallel.

	     The maximum number	of record entries to allow in a	single jour-

	     Controls whether entries in a journal will	be optimized by	com-
	     bining overlapping	I/Os into a single I/O and reordering the en-
	     tries in a	journal.  This can be disabled by setting the sysctl
	     to	0.

     The string	and integer information	available for the cache	level is de-
     tailed below.  The	changeable column shows	whether	a process with appro-
     priate privilege may change the value.

	   sysctl name		   Type		 Changeable
	   used			   integer	 no
	   limit		   integer	 yes
	   divisor		   integer	 no
	   switch		   integer	 yes
	   misses		   integer	 yes
	   alloc_failures	   integer	 yes

     used    The number	of bytes currently allocated to	the cache.

     limit   The maximum number	of bytes to be allocated to the	cache.

	     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.

     switch  Force a journal switch when this percentage of cache has been

     misses  The number	of cache misses, when data has been read, but was not
	     found in the cache.

	     The number	of times memory	failed to be allocated to the cache
	     because the cache limit was hit.

     The string	and integer information	available for the statistics level is
     detailed below.  The changeable column shows whether a process with ap-
     propriate privilege may change the	value.

	   sysctl name		  Type		Changeable
	   skipped_bytes	  integer	yes
	   combined_ios		  integer	yes
	   switches		  integer	yes
	   wait_for_copy	  integer	yes
	   journal_full		  integer	yes
	   low_mem		  integer	yes

	     The number	of bytes skipped.

	     The number	of I/Os	which were combined by journal optimization.

	     The number	of journal switches.

	     The number	of times the journal switch process had	to wait	for
	     the previous journal copy to complete.

	     The number	of times the journal was almost	full, forcing a	jour-
	     nal switch.

	     The number	of times the low_mem hook was called.

     geom(4), geom(8), mount(8), newfs(8), tunefs(8), umount(8)

     The gjournal utility appeared in FreeBSD 7.0.

     Pawel Jakub Dawidek <>

BSD			       February	17, 2009			   BSD


Want to link to this manual page? Use this URL:

home | help