wl container - Container commands

Synopsis

wl {container|containers} list
wl container info NAME
wl container delete [--force] [--cascade] NAME [NAME ...]
wl container create [--owner <user>] --path <path> [--path <path2> ...] [--storage-template <storage_template>]
wl container create-cache --template <template_name> <container>
wl container delete-cache <container>
wl container update [--storage <storage>] <container>
wl container mount []
wl container unmount
wl container modify [] <file>
wl container publish <container>
wl container unpublish <container>

Description

Todo

Write some general info about containers.

When the type of manifest is known, you can refer to a manifest just by a short name (e.g. wl container sign C1 will know to look for ~/.config/wildland/containers/C1.yaml).

Commands

wl {container|containers} list

List known containers.

wl container info NAME

Display a short summary of a single container. The information is equivalent to wl container list, but for one container only.

wl container delete [--force] [--cascade] [--no-unpublish] NAME [NAME ...]

Delete a container from local filesystem and unpublish it, if published.

--force, -f

Delete even if the container refers to local storage manifests.

--cascade

Delete together with all local storage manifests.

--no-unpublish, -n

Do not attempt to unpublish the container before deleting it.

wl container create [--owner <user>] [--path <path>] [--path <path2> ...] [--storage-template <storage-template>] [--encrypt-manifest/--no-encrypt-manifest] [--access <user>] [--no-publish]

Create a new container manifest.

--path <path>

The paths under which the container will be mounted.

--owner <user>, --user <user>

The owner of the container. The --user alias is deprecated.

Todo

Write the config name for default user.

--title <title>

Title of the container. Used when generating paths based on categories.

--category </path/to/category>

Category to use in generating paths. Requires –title. May be provided multiple times.

-u, --update-user

Add the container to the user manifest.

-n, --no-update-user

Don’t add the container to the user manifest. This is the default.

--storage-template <storage_template>, --template

Create storages for a container with a given storage-template.

--local-dir <local_dir>

Local directory to be passed to storage templates as a parameter. Requires –storage-template.

--encrypt-manifest

Encrypt container manifest so that it’s readable only by the owner. This is the default.

--no-encrypt-manifest

Do not encrypt container manifest at all.

--access USER

Allow an additional user or user path access to this container manifest. This requires –encrypt-manifest (which is true by default).

--no-publish

Do not publish the container after creation. By default, if the container owner has proper infrastructure defined in the user manifest, the container is published.

wl container create-cache --template <template_name> <container> [<container>...]

Create a cache storage for container(s) from a template. This is used to speed up accessing slow remote storages like s3. The template should usually be the default local storage one (wl template create local –location /path/to/cache/root template_name).

On the first container mount, old primary storage’s content (usually a slow remote one) is copied to the cache storage. From then on the cache storage becomes container’s primary storage when the container is mounted. Old primary storage is kept in sync with the cache when mounted.

Cache storage is created based on the template provided. Because the purpose of the cache storage is to be fast, it’s best to use a local storage template unless some specific setup is needed. When using a default local storage template as outlined above, the cache storage directory is /path/to/cache/root/container_uuid.

Cache manifests are stored in <Wildland config root>/cache directory and are storage manifests. Wildland storage commands can be used to display or manually edit them. They have file names in the form of owner_id.container_uuid.storage.yaml.

-t, --template <template_name>

Name of the storage template to use.

wl container delete-cache <container> [<container>...]

Deletes cache storage associated with container(s).

wl container update [--storage <storage>] <container>

Update a container manifest.

--storage <storage>

The storage to use.

This option can be repeated.

wl container mount [--verbose/-v] [--remount/--no-remount] [options] <container> [<container>...]

Mount a container given by name or path to manifest. The Wildland system has to be started first, see wl start. Wildland paths are supported too, including unambiguous (with wildcards or else) ones. For example: wildland:@default:/path/to/user:*:

The container(s) will be mounted under paths declared in the container manifest, nested into a owner-specific directory. If the container owner is the default user (see wl start), then the container will be mounted directly under the FUSE root directory. Otherwise, it will be mounted under paths defined by bridges between users. In addition, containers are always mounted nested under /.users/<user-id>:, also when the container is owned by the default user. Directories that transition to another user (like - bridges) are marked with colon (:) at the end, thus the path in the filesystem looks very similar to WL path. To avoid confusion, any other colon within container or bridge path is replaced with underscore (_).

For example:

  • default owner is set to UserA (user id 0xaaa…)

  • there is a bridge owned by UserA pointing at UserB (user id 0xbbb…) under path /people/UserB

  • there is a bridge owned by UserB pointing at UserC (user id 0xccc…) under path /people/UserC

  • user mounts a container of UserC with paths /docs/projectX and /timeline/2021-01-02

The mounted container will be available under the following paths: - /.users/0xccc…:/docs/projectX and /.users/0xccc…:/timeline/2021-01-02 - /people/UserB:/people/UserC:/docs/projectX and /people/UserB:/people/UserC:/timeline/2021-01-02

The second point is built from bridges from UserA to UserC.

In some cases, there might be multiple possible bridges or multiple containers in users’ manifests catalogs. In both circumstances all paths will be considered, but cycles will be avoided.

-r, --remount

Replace the container currently mounted, if any. The container is identified by its first path.

-n, --no-remount

Don’t replace existing container. If the container is already mounted, the command will fail. This is the default.

-s, --save

Add the containers to default-containers in configuration file, so that they will be mounted at startup.

--import-users

Import user manifests encountered when loading the containers to mount. This is applicable when contianer is given as a WL path. When enabled, further mounts of the same user container can reference the user directly, instead of through a directory (specifically - a bridge manifest in it). Enabled by default.

--no-import-users

Do not import user manifests when mounting a container through a WL path.

-w, --with-subcontainers

Mount the subcontainers of those containers. Subcontainers are mounted recursively (i.e. if any subcontainers provide own set of subcontainers, mount those too). This is the default.

-W, --without-subcontainers

Do not mount the subcontainers of those containers.

-b, --only-subcontainers

If container contains any subcontainers then mount just the subcontainers and skip mounting the container’s storage itself.

-c, --with-cache

Create and use a cache storage for the container using the default cache template (see wl set-default-cache). See wl container create-cache for details about caches.

--cache-template <template_name>

Create and use a cache storage for the container from the given template. See wl container create-cache.

-l, --list-all

During mount, list all the containers to be mounted and result of mount (changed/not changed). Can be very long in case of Wildland paths or numerous subcontainers.

-m, --manifests-catalog

Allow to mount manifests catalog containers.

Currently if a user wants to mount the whole forest (i.e. all the containers), the supported syntax is this:

wl c mount :/forests/User:*:

But we also support mounting of the manifests catalog containers, i.e. those that hold the manifests for the forest, using the following syntax:

wl c mount :/forests/User:

This latter syntax is very similar to the above syntax and it is very easy for users to confuse the two.

In order to better differentiate between these two actions, the second syntax can be made more explicit using the –manifests-catalog option:

wl c mount –manifests-catalog :/forests/User:

wl container mount-watch <pattern> [<pattern>...]

Mount a list of containers from manifests in Wildland filesystem, then watch the filesystem for change.

The Wildland system has to be mounted first, see wl start.

Example:

wl container mount-watch '~/wildland/mynotes/*/*.yaml'

This will attempt to mount, unmount and remount containers as the files matched by /*/*.yaml change.

The pattern can be also a container WL path, either specific (like wildland::/users/alice:/docs/notes:), or wildcard (like wildland::/users/alice:*:).

Make sure to use quotation marks, or the wildcard patterns will be expanded by the shell.

wl container add-mount-watch <pattern> [<pattern>...]

Modify mount-watch to watch for additional patterns. See wl container mount-watch for syntax requirements.

Container mount-watch must be running. The Wildland system has to be mounted first, see wl start.

Example:

wl container add-mount-watch '~/wildland/mynotes/*/*.yaml'

wl container stop-mount-watch

Stop the current mount-watch daemon.

wl container unmount [--path] [--all] [--with-subcontainers/--without-subcontainers] [--undo-save] <container>

--path <path>

Mount path to search for.

--all

Unmount all mounted storages.

-w, --with-subcontainers

Unmount the subcontainers of those containers. Subcontainers are unmounted recursively (i.e. if any subcontainer provides own set of subcontainers, unmount those too). This is the default.

-W, --without-subcontainers

Do not unmount the subcontainers of those containers.

-u, --undo-save

Undo wl container mount --save <container>. <container> must be specified exactly the same as when running wl container mount --save <container>.

For example, if you run:

wl c mount --save '~/mnt/.manifests/.uuid/*'

then it will not work:

wl c unmount --undo-save '~/mnt/.manifests/.uuid/*.yaml'

Also make sure to quote ~/mnt/.manifests/.uuid/*.yaml unless you want it to be expanded by your shell instead of Wildland itself.

wl container publish <container>

Publish a container manifest into user’s manifests catalog (first container from the catalog that provides read-write storage will be used).

wl container unpublish <container>

Unublish a container manifest from the whole of a user’s manifests catalog.

wl container {sign|verify} [...]

See wl sign and wl verify documentation.

wl container edit PATH

Edit, sign and republish a container. The command will launch an editor and validate the edited file before signing and republishing it.

If an absolute path, container name or file:// URL is passed, the container will be considered a local file.

--editor <editor>

Use custom editor instead of the one configured with usual VISUAL or EDITOR variables.

-r, --remount

If editing a container, attempt to remount it afterwards. This is the default

-n, --no-remount

If editing a container, do not attempt to remount it afterwards.

--publish, -p

By default, if the container is already published, the modified version of the container manifest will be republished.

--no-publish, -P

Do not attempt to republish the container after modification.

wl container dump PATH

The command will output manifest contents (without signature and by default decrypted) in a machine-readable way.

If an absolute path, container name or file:// URL is passed, the container will be considered a local file.

-d, --decrypt

Decrypt any encrypted fields, if possible. This is the default.

-n, --no-decrypt

Do not decrypt any encrypted fields.

wl container sync [--target-storage <id_or_type>] [--source-storage <id_or_type>] [--one-shot] [--no-wait] <container>

Start synchronizing two of a container’s storages, by default the first local storage with the first non-local storage in the manifest).

--source-storage <id_or_type>

Specify which should be the source storage for syncing; can be specified as a backend-id or as storage type (e.g. ‘s3’). If not –one-shot, source and target storages are symmetric.

--target-storage <id_or_type>

Specify which should be the target storage for syncing; can be specified as a backend-id or as storage type (e.g. ‘s3’). The choice will be saved in config and used as default in future container syncs. If not –one-shot, source and target storages are symmetric.

--one-shot

Perform one-time sync, do not maintain sync.

--no-wait

Do not wait for a one-time sync to finish, run in the background. Requires –one-shot.

wl container stop-sync <container>

Stop synchronizing container’s storages.

wl container list-conflicts [--force-scan] <container>

List all conflicts detected by container sync.

--force-scan

Force checking all files in all storages and their hashes. Can be slow and bandwidth-intensive.

wl container duplicate [--new-name <new-name>] <container>

Duplicate a given container as a container called <new-name>, optionally adding it to the user manifest. UUIDs and backend-ids are updated, everything else remains the same.

--new-name <new-name>

Name for the newly created container.

wl container modify [--add-path <path> ...] [--del-path <path> ...] [--add-access <user> ...] [--del-access <user> ...] [--add-category <path> ...] [--del-category <path> ...] [--del-storage <storage>] [--title] [--encrypt-manifest] [--no-encrypt-manifest] [--publish/--no-publish] [--remount/--no-remount] <file>

Modify a container manifest given by <file>.

--add-path

Path to add. Can be repeated.

--del-path

Path to remove. Can be repeated.

--add-access

User or user path to add access for. Can be repeated.

--del-access

User to revoke access from. Can be repeated.

--add-category

Category to add. Can be repeated.

--del-category

Category to remove. Can be repeated.

--del-storage

Storages to remove. Can be either the backend_id of a storage or position in storage list (starting from 0). Can be repeated.

--title

Title to set.

--encrypt-manifest

Encrypt manifest given by <file> so that it’s only readable by its owner.

--no-encrypt-manifest

Stop encrypting manifest given by <file>.

--publish, -p

By default, if the container is already published, the modified version of the container manifest will be republished.

--no-publish, -P

Do not attempt to republish the container after modification.

--remount, -r

By default, if the container is already mounted, the modified version of the container will be remounted.

--no-remount, -n

Do not attempt to remounting the container after modification.

wl container find <file>

Show which container exposes the mounted file.