Usage Vault Console Tool (VLT)
NOTE: Parts of the following documentation are outdated and need review
The console tool is called vlt and has the following usage:
$vlt --help
----------------------------------------------------------------------------------------------------------------------------------------
Jackrabbit FileVault [version 3.5.7-SNAPSHOT] copyright 2013-2021 by Apache Software Foundation. See LICENSE.txt for more information.
----------------------------------------------------------------------------------------------------------------------------------------
Usage:
vlt [options] <command> [arg1 [arg2 [arg3] ..]]
----------------------------------------------------------------------------------------------------------------------------------------
Global options:
-Xjcrlog <arg> Extended JcrLog options (omit argument for help)
-Xdavex <arg> Extended JCR remoting options (omit argument for help)
--credentials <arg> The default credentials to use
--update-credentials if present the credentials-to-host list is updated in the ~/.vault/auth.xml
--config <arg> The JcrFs config to use
--useSystemProperties Evaluating the default Java system properties for connection settings.
--allowSelfSignedCertificates Allows to connect to HTTPS repository urls whose certificate is self-signed.
--disableHostnameValidator Disables hostname validation for HTTPS repository urls.
--connectionTimeoutMs <arg> The connection timeout in milliseconds.
--requestTimeoutMs <arg> The request timeout in milliseconds.
--socketTimeoutMs <arg> The socket timeout in milliseconds.
--proxyHost <arg> The host of the proxy to use.
--proxyPort <arg> The port where the proxy is running (requires proxyHost as well).
--proxyProtocol <arg> The protocol for which to use the proxy (requires proxyHost as well). If not set proxy is used for both HTTP and HTTPS.
--proxyUsername <arg> The username to use for authentication at the proxy (requires proxyHost as well).
--proxyPassword <arg> The password to use for authentication at the proxy (requires proxyUsername as well)
-v (--verbose) verbose output
-q (--quiet) print as little as possible
--version print the version information and exit
--log-level <level> the logback log level
-h (--help) <command> print this help
Commands:
export Export the Vault filesystem
import Import a Vault filesystem
checkout (co) Checkout a Vault file system
status (st) Print the status of working copy files and directories.
update (up) Bring changes from the repository into the working copy.
info Displays information about a local file.
commit (ci) Send changes from your working copy to the repository.
revert (rev) Restore pristine working copy file (undo most local edits).
resolved (res) Remove 'conflicted' state on working copy files or directories.
propget (pg) Print the value of a property on files or directories.
proplist (pl) Print the properties on files or directories.
propset (ps) Set the value of a property on files or directories.
add Put files and directories under version control.
delete (del,rm) Remove files and directories from version control.
diff (di) Display the differences between two paths.
rcp Remote copy of repository content.
sync Control vault sync service
format Formats vault docview files.
console Run an interactive console
----------------------------------------------------------------------------------------------------------------------------------------
Checkout
todo
Checkin
todo
Adding / Removing Files
todo
Logging
vlt uses logback for logging. To adjust the logging configuration you can either use the
cli option --log-level <level> or edit the logback xml configuration
at etc/logback.xml for more granular settings.
Vault Sync
The vault sync service is used to synchronize repository content with a local filesystem representation and vice versa. This is achieved by installing an OSGi service that will listen for repository changes and scans the filesystem contents periodically. It uses the same serialization format as vault for mapping the repository contents to disk. For accessing the repository it uses an Apache Sling service (therefore can only be started when Sling JCR API and an according implementation bundle are available).
The vault sync service is a development tool and it is highly discouraged to use it on a productive system. Also note that the service can only sync with the local filesystem and cannot be used for remote development.
Currently it only supports simple files (nt:file) and folders (nt:hierachyNode) but detects special vault serialized files
(.content.xml, dialog.xml, etc) and ignores them silently (JCRVLT-125). Thus it is possible to use vault sync on a default vlt
checkout.
Installation and Configuration
The vault sync service is provided as bundle which needs to be installed in Oak (or any other sling runtime). Once the service is running it can be configured with the following parameters:
- vault.sync.syncroots
- One or many local filesystem paths that define the sync roots.
- vault.sync.fscheckinterval
- Frequency (in seconds) of which the filesystem should be scanned for changes. default is 5 seconds.
- vault.sync.enabled
- General flag that enables/disables the service
Note: It is advisable to configure the service via a sling:OsgiConfig node with the name
org.apache.jackrabbit.vault.sync.impl.VaultSyncServiceImpl. Once the service has configured sync roots it will
initialize the sync root with the following files:
.vlt-sync-config.properties- Per sync-root config
.vlt-sync.log- log file that contains information about the operations performed during syncing
.vlt-sync-filter.xml- filter that is needed to configure what portions of the repository are synced.
The vault sync service can also be installed using the vlt command line tool. See Vlt Integration below.
.vlt-sync-filter.xml
The sync filter has the format of a normal vault workspace filter. If the sync root lies on a vlt checkout, specifically
points to a jcr_root directory of a such, then no .vlt-sync-filter.xml is initialized in the sync root, but the one
defined by the respective vlt checkout is used. This is usually META-INF/vault/filter.xml.
.vlt-sync-config.properties
This config has the following default content:
#
# Vault Sync Config File
#
# Note: Changes to this file are detected automatically if the Vault Sync Service is
# running and this directory is configured as sync root.
#
# Supported Properties:
# ---------------------
#
# disabled = ( "true" | "false" )
# Defines if syncing of this directory is generally disabled. It can be useful
# to disabled syncing temporarily if structural changes need to be done that required
# several modifications.
#
# defaults to: false
disabled=false
# sync-once= ( "" | "JCR2FS" | "FS2JCR" )
# If non empty the next scan will trigger a full sync in the direction indicated.
#
# JCR2FS: 'export' all content in the JCR repository and write to the local disk.
# FS2JCR: 'import' all content from the disk into the JCR repository.
#
# defaults to: ""
sync-once=
# sync-log = <filename>
# Defines the filename of the sync log.
#
# defaults to: .vlt-sync.log
#
#sync-log=.vlt-sync.log
A note to sync-one: This property is used to trigger a directional full sync between the repository and the file
system (usinig JCR2FS) or vice versa (using FS2JCR). This is especially useful when installing vault sync for the
first time or adding a new sync root. Allow a maximum of 5 seconds (or whatever you configured the sync interval to be)
for a configuration change to be detected. Check the .vlt-sync.log or the error.log of your instance for progress or
errors.
For example you started of a project directly in the repository using CRXDE Lite and now decide to use your local IDE
for further development. After configuring the sync root and the filter, you would set the sync-once property to
JCR2FS to get all your files created in the local sync root.
For example you start with a fresh repository and want to import local files that you retrieved from a SCM. After
configuring the sync root and the filter (which should be under SCM, too), you would set the sync-once property
to FS2JCR.
Operation
Once properly configured and running you should do an initial full sync to get system in a synchronized state. to do so, follow the notes above regarding the sync-once configuration property. After that each repository modification within the specified filter will trigger a repository-to-filesystem synchronization of the modified nodes (see initial note on supported serializations). The repository changes are applied almost immediately since JCR observation events are pushed to it's listeners.
On each sync interval, the service scans the filesystem for changes and eventually synchronizes the changes back with the repository. So allow a maximum of 5 seconds (or whatever you configured the sync interval to be) after you made changes to the local files.
Note: Be very careful on structural changes on the local filesystem as they might result in removing potentially large trees in the repository.
vlt integration
The vault sync service can be used standalone or together with a vlt checkout. using the later, using the later
initialization is easy as executing: vlt sync on the command line. the following sync related commands are available
by vlt (as of version 2.3.22):
$ vlt sync --help
Usage:
sync -v|--force|-u <uri> <command> <localPath>
Description:
Allows to control the vault sync service. Without any arguments this command tries to put the current CWD under sync control. If executed within a vlt checkout, it uses the respective filter and host to configure the syncing. If executed outside of a vlt checkout, it registers synchronization only if the directory is empty.
Subcommands:
install Installs the Vault Sync service on the remote server
status (st) Display status information.
register Register a new sync directory
unregister Unregisters a sync directory
Most of the commands take an optional local path as argument which then specifies the sync directory. If the --uri is omitted it is auto-detected from the current vault checkout.
Note: the vault sync service creates a .vlt-sync-config.properties in the sync directory. See the inline comments for further options.
Examples:
Listing sync roots of a server:
vlt --credentials admin:admin sync --uri http://localhost:8080/crx status
Add the current CWD as sync directory:
vlt sync register
Options:
-v (--verbose) verbose output
--force force certain commands to execute.
-u (--uri) <uri> Specifies the URI of the sync host.
<command> Sync Command
<localPath> local path (optional)
installing the service using vlt
The vlt sync install command can be used to install the vault sync service bundle and configuration automatically.
the bundle is installed below /libs/system/vault/install and the config node is created at
/libs/system/vault/org.apache.jackrabbit.vault.sync.impl.VaultSyncServiceImpl. Initially the service is enabled but
no sync roots are configured.
Example:
$ vlt --credentials admin:admin sync --uri http://localhost:8080/crx install
displaying the service status
The status command can be used to display information about the running sync service. Note that the status command does
not fetch any live data from the service but rather reads the configuration at /libs/system/vault/org.apache.jackrabbit.vault.sync.impl.VaultSyncServiceImpl
Example:
$ vlt sync status --uri http://localhost:4502/crx
Connecting via JCR remoting to http://localhost:4502/crx/server
Listing sync status for http://localhost:4502/crx/server/-/jcr:root
- Sync service is enabled.
- No sync directories configured.
adding/removing sync roots
The register and unregister commands are used to add and remove sync roots from the configuration.
Example (executed in a vlt checkout):
$ vlt sync register
Connecting via JCR remoting to http://localhost:4502/crx/server
Added new sync directory: /tmp/workspace/vltsync/jcr_root
$ vlt sync status
Connecting via JCR remoting to http://localhost:4502/crx/server
Listing sync status for http://localhost:4502/crx/server/-/jcr:root
- Sync service is enabled.
- syncing directory: /tmp/workspace/vltsync/jcr_root
Quick setup
The most common task is probably installing the service and register the current vlt checkout as sync root. this can be done using the sync command without arguments.
Example (executed in a vlt checkout):
$ vlt sync
Connecting via JCR remoting to http://localhost:4502/crx/server
Starting initialization of sync service in existing vlt checkout /tmp/workspace/vltsync/jcr_root for http://localhost:4502/crx/server/-/jcr:root
Preparing to install vault-sync-2.3.22.jar...
Updated bundle: vault-sync-2.3.22.jar
Created new config at /libs/crx/vault/config/org.apache.jackrabbit.vault.sync.impl.VaultSyncServiceImpl
Added new sync directory: /tmp/workspace/vltsync/jcr_root
The directory /tmp/workspace/vltsync/jcr_root is now enabled for syncing.
You might perform a ‘sync-once’ by setting the
appropriate flag in the /tmp/workspace/vltsync/jcr_root/.vlt-sync-config.properties file.