MOUNTCTL(8)

NAME
mountctl - control journaling and other features on mounted file systems

SYNOPSIS
mountctl -l {mountpt | tag | mountpt:tag}
mountctl -a [-2] [-w/W output_path] [-x/X filedesc] [-o options] mountpt:tag
mountctl -r [-2] [-w/W output_path] [-x/X filedesc] mountpt:tag
mountctl -d {mountpt | tag | mountpt:tag}
mountctl -m [-o options] {mountpt | tag | mountpt:tag}
mountctl -FZSCA {mountpt | tag | mountpt:tag}

DESCRIPTION
The mountctl utility manages journaling and (eventually) other features on a mounted filesystem. Note that a mount point path must begin with ‘/’, and tag names must not begin with ‘/’.

mountctl -l will list all installed journals in the system or on a particular mount point or tag, including their current state of operation.

mountctl -a will add a new journal to a mount point. A mount may have any number of journals associated with it. If no output path is specified the journal will be written to the standard output. Options may be specified as described in the OPTION KEYWORDS section. The tag is required and must be unique relative to any given mount, but you can use the same tag on multiple mount points if you wish (and control them all together by referencing that tag). The output path may represent any streamable entity. You can, for example, output to a pipe into a program which does further buffering or processing of the journal. WARNING A stalled journaling descriptor will stall the filesystem. Eventually a kernel-implemented swap backing will be available for journals but that is not the case at the moment.

mountctl -r will restart an existing journal, directing it to a new file descriptor. A shutdown is sent to the old journal and the system waits for the return direction (if running full-duplex) to EOF. The new descriptor is then installed and the FIFO index is reset to the last acknowledged transaction. Clients scanning a journal across such a disconnect must check for repeated transaction ids since some overlap between the old and new journal may occur.

mountctl -d will remove the specified journal(s). A mount point, a tag, or both may be specified. This function will operate on all matching journals.

mountctl -m will modify the options associated with an existing journal. Options are specified in the OPTION KEYWORDS section.

OTHER OPTIONS

-2  Specify full-duplex operation. The kernel will not throw away journal data in its internal FIFO until the transaction id is acknowledged. This requires a full-duplex journaling descriptor. Note that shell pipes are full-duplex-capable.

-F  Flush a journal, equivalent to the flush keyword. This option implies -m.

-Z  Freeze a journal, equivalent to the freeze keyword. This option implies -m if -a or -d are not specified.

-S  Start a stopped journal, equivalent to the start keyword. This option implies -m.

-C  Close a journal, equivalent to the close keyword. This option implies -m.

-A  Abort a journal, equivalent to the abort keyword. This option implies -m.

-w output_path
    Change a journal's stream descriptor to the specified path. This option implies -m if -a or -d are not specified. The target file must not reside on the same filesystem being journaled.

-W output_path
    Same as -w but overrides target safety checks.

-x filedesc
    Change a journal's stream descriptor to the specified file descriptor number. This option implies -m if -a or -d are not specified. The target file must not reside on the same filesystem being journaled.

-X filedesc
    Same as -x but overrides target safety checks.

-o options
    Specify options, see OPTION KEYWORDS.

OPTION KEYWORDS
Options keywords may be comma delimited without whitespace within a single -o or via multiple -o options. Some keywords require a value which is specified as keyword=value. Any option may be prefixed with ‘no’ or ‘non’ to turn off the option. Some options are one-shot and have no ‘no’ or ‘non’ equivalent.

The options are as follows:

reversable
    Generate a reversable journaling stream. This allows the target to run the journal backwards as well as forwards to ‘undo’ operations. This is the default.

twoway
    Indicate that the journaling stream is a two-way stream and that transaction id acknowledgements will be returned. This option is the same as the -2 option.

memfifo=size[k,m]
    Specify the size of the in-kernel memory FIFO used to buffer the journaling stream between processes doing filesystem operations and the worker thread writing out the journal. Since the kernel has limited virtual memory buffers larger than 4MB are not recommended.

swapfifo=size[k,m,g]
    Specify the size of the kernel-managed swap-backed FIFO used to buffer overflows.

path=filepath
    Specify where the journal's output stream should be directed. Note that the -w option is equivalent to specifying the path option. Both should not be specified.

fd=filedesc
    Specify where the journal's output stream should be directed by handing over a file descriptor. Use file descriptor 1 if you wish to output the journal to the current stdout. Note that the -w option is equivalent to specifying the path option. Both should not be specified.

freeze
    Freeze the worker thread. This may cause the filesystem to stall once the memory fifo has filled up. A freeze point record will be written to the journal. If used as part of the creation of a new journal via -a, this option will prevent any initial output to the journal and a freeze point record will NOT be written. Again, the filesystem will stall if the memory fifo fills up.

start
    Start or restart the worker thread after a freeze.

close
    Close the journal. Any transactions still under way will be allowed to complete, a closing record will be generated, and the journaling descriptor will be closed. If the connection is two-way the journal will away a final acknowledgement of the closing record before closing the descriptor.

abort
    Close the journal. Any currently buffered data will be aborted. No close record is written. The journaling stream is immediately closed.

flush
    Flush the journal. All currently buffered data is flushed. The command does not return until the write succeeds and, if the connection is two-way, and acknowledgement has been returned for journaled data buffered at the time the flush was issued.

SEE ALSO
mount(2), mountctl(2), jscan(8)

HISTORY
The mountctl utility first appeared in DragonFly 1.2.

CAVEATS
This utility is currently under construction and not all features have been implemented yet. In fact, most have not.