Cosnim Commands Reference 

Using the Command-Line Interface 

All system administration and operations are performed using the cosnim command found under the installation directory.

Global Options 

Most commands accept the following additional GLOBAL_OPTIONS:

Synopsis 

cosnim COMMAND… [-h, --help] [-v, --verbose] [-q, --quiet] [-c, --config=CONFIG] [-o=OPTION=VALUE,…] [--debug] [--events=EVENTS] [--checks=CHECKS] [--version]

Options 

-h, --help: Display a summary of the command’s arguments and options.

-v, --verbose: Increase the verbosity of the messages. Repeat this option multiple times to display more and more information messages. Beware, this may result in voluminous output.

-q, --quiet: Decrease the verbosity of the messages. Specify the option once to reduce informational messages, twice to reduce warning messages, and three times or more to suppress error and critical messages.

-c, --config=CONFIG

Select a configuration file to run the command. If this option is not specified, the command will search for a configuration file in the following locations, selecting the first one it finds:

The file specified in the COSNIM_CONFIG environment variable.
The file config.yml in the current directory.
The file config/config.yml in a subdirectory of the current directory.

-o, --options=OPTION=VALUE,...

Override specific configuration options. This can be useful to alter the command’s behavior without modifying the configuration file.

Specify options in the form OPTION=VALUE, where OPTION is the dot-delimited path of the configuration option, and VALUE is the new internal value to assign as follows:

VALUE	Interpretation	Yaml configuration equivalent
True	Activates the option	yes, true, on
False	Deactivates the option	no, false, off
None	Nullifies the option	null
‘string’	Assign a string option	<string> or ‘<string>’
<number>	Assign a numerical option	<number>
[value,…]	Assigns a list of values	[ value, value, …]
{key:value, …}	Assign a map of values	{ key: value, key: value, …}

For example, with a YAML configuration file containing:

mount:
   volume: My Files
   direct_io: no

Use the following option to activate direct I/O:

cosnim mount -o mount.direct_io=True

--debug: (debugging) print additional information when errors occur. Use as directed by support.

--events=EVENTS: (debugging) trace specific internal events. Use as directed by support.

--checks=CHECKLEVEL: (debugging) control the level of internal checks. Use as directed by support.

--version: Display the current software version and exit. See also cosnim show version.

Mounting and Unmounting 

cosnim mount 

Synopsis 

cosnim mount [--ro, --rw] [OPTIONS] [GLOBAL_OPTIONS]

Description 

Mount a continuum as a live filesystem as defined in the configuration.

Options 

--ro, --readonly: Force the filesystem to be mounted read-only to prevent any modification.

--rw, --readwrite: Force the filesystem to be mounted in read-write mode to allow modifications.

Warning

Mounting a filesystem in read-write mode in multiple clients/users with a continuum that has been configured for unshared use (share_level <= 1) may lead to crashes and possible data corruption.

-r, --remount: Unmount and remount the filesystem if it’s already mounted. Useful to alter a mount’s options without having to unmount it first.

--mountpoint=PATH: Override the configuration and mount the filesystem at a specific mountpoint.

Note

If you mount the same continuum under different mount points, each mountpoint will behave as if separate users mounted it. Depending on your product (Backup, Vault or Nexus) and the configuration sharing options, this may not give the expected results. For example, attempting to share a continuum using Cosnim Backup on two different mountpoints may cause one of the two mountpoints to fail with a sharing violation when data is altered.

--timeout=SECS: The number of seconds to wait for the filesystem to unmount before giving up. A filesystem may take longer to unmount because another user is actively using it. To force the filesystem to unmount even if there are active users, use cosnim unmount --force. The default timeout is 5 seconds.

--mkdir: Create the mountpoint directory automatically if it doesn’t exist.

--no-mkdir: Don’t create the mountpoint directory automatically. If the directory does not exist, the mount command will fail.

-f, --foreground: Run the command in the foreground and display all messages on the console.

--background: Run the command in the foreground and display all messages on the console. This is the default.

Unmount 

Synopsis 

cosnim unmount [-f, --force] [--all] [--timeout=TIMEOUT] [MOUNTPOINTS …] [GLOBAL_OPTIONS]

Description 

Unmount the specified MOUNTPOINTS. If MOUNTPOINTS is omitted, the mountpoint in the current configuration is unmounted.

Options 

-f, --force: Force unmounting the mountpoint even if the filesystem is still busy. This may cause errors in users and applications currently using the filesystem.

--all: Unmount all Cosnim mountpoints, configured or not. The default is to unmount only the filesystem defined in the current configuration.

--timeout=SECS: The number of seconds to wait for the filesystem to unmount before giving up. A filesystem may take longer to unmount because another user is actively using it. To force the filesystem to unmount even if there are active users, use cosnim unmount --force. The default timeout is 5 seconds.

Show Mount 

Synopsis 

cosnim show mount [--all] [--long] [MOUNTPOINTS …] [GLOBAL_OPTIONS]

Description 

Show the state of the MOUNTPOINTS. If MOUNTPOINTS is omitted, the state of the currently configured mountpoint is displayed.

Options 

--all: Show all Cosnim mountpoints, including those not defined in the current configuration.

-l, --long: Also display the OS mount options and attributes.

Check Mount 

Synopsis 

cosnim check mount [--all] [--long] [MOUNTPOINTS …] [GLOBAL_OPTIONS]

Description 

Identical to the cosnim show mount command, except that the command returns an error status code if the specified mountpoints are not currently mounted. This is useful for scripts and automated tools.

Relay and Gateway Management 

Start Relay 

Synopsis 

cosnim start relay RELAY [-f, --foreground] [GLOBAL_OPTIONS]

Description 

Starts the given RELAY on the current host. The RELAY server must be defined in the current configuration.

Options 

-f, --foreground

Run the relay in the foreground instead of the background. If running in the background, it is strongly suggested to also redirect the command’s output to a file, such as in:

cosnim start relay primary &> logfile

Start Gateway 

Synopsis 

cosnim start gateway GATEWAY [-f, --foreground] [GLOBAL_OPTIONS]

Description 

Starts the given GATEWAY on the current host. The GATEWAY server must be defined in the current configuration.

Options 

-f, --foreground

Run the gateway in the foreground instead of the background. If running in the background, it is strongly suggested to also redirect the command’s output to a file, such as in:

cosnim start relay primary &> logfile

Continuum Management 

Create Continuum 

Synopsis 

cosnim create continuum [GLOBAL_OPTIONS]

Description 

Create a continuum by creating strategic capsules in the configured storage hubs. All hubs must be empty for the command to succeed. See cosnim expand continuum to expand a continuum to use additional storage hubs.

About continuum creation 

A Cosnim continuum is, at its core, a collection of storage hubs and capsules, where capsules are internally bonded to each other to represent the user’s data. There is no actual authority, server, or coordination center in a continuum; a continuum is spawned into existence simply by creating a single capsule in each storage hub that binds it with the other capsules. In that sense, other than agreeing on storage providers’ prefixes and namespaces to avoid collisions (see Installation & Configuration), creating a continuum is a deceptively simple operation.

Extend Continuum 

Synopsis 

cosnim extend continuum [--create] [GLOBAL_OPTIONS]

Description 

Extends a continuum to use new storage hubs.

This is done by creating capsules in newer storage hubs bonded to existing ones, extending the continuum to use the new storage hubs. The command will fail if the new hubs already contain capsules bonded to different continuums.

Options 

--create: Creates a new continuum if one does not yet exist in any storage hub. This option may be useful in automation scripts that don’t need/want to distinguish between creating and expanding a continuum.

Show Continuum 

Synopsis 

cosnim show continuum [-l, --long] [--namerkey] [GLOBAL_OPTIONS]

Description 

Display the status of the continuum. Without options, this displays the current availability of the continuum and its UUID.

Options 

-l, --long: Also display the internal states of the continuum. This includes the current time-travel point representing the precise state of the continuum when the command was executed.

--namerkey: Also display the namerkey. This option is mainly for Cosnim support.

Keychain Management 

KEYCHAIN OPTIONS 

All keychain management commands support the following options:

Synopsis 

cosnim KEYCHAIN_COMMAND [--keychain=KEYCHAIN] [--prompt-passphrase | --passphrase=PASSPHRASE | --read-passphrase=FILE ]

--keychain=KEYCHAIN: Path and name of the keychain file. If omitted, the name is obtained from the configuration file.

--prompt-passphrase: Prompt for the passphrase. This is the default.

--read-passphrase=FILE: Read the keychain passphrase from FILE.

--passphrase=PASSPHRASE: Specify the passphrase as an argument.

Warning

Specifying a passphrase as an argument with --passphrase=PASSPHRASE can be a security risk! For better security, use --prompt-passphrase or --read-passphrase.

Create Keychain 

Synopsis 

cosnim create keychain [--iterations=1000] [--no-passphrase] [KEYCHAIN_OPTIONS] [GLOBAL_OPTIONS]

Description 

Creates a new keychain file. A default encryption key block is automatically generated. Other credentials keys can be added with the cosnim generate key or cosnim import key command.

Options 

--no-passphrase

Don’t protect the keychain with a passphrase. If this option is not specified, the keychain will be protected with a passphrase, prompting the user if necessary.

See the KEYCHAIN_OPTIONS --passphrase=PASSPHRASE, --prompt-passphrase and --read-passphrase=FILE options for ways of specifying a passphrase.

Warning

Always store unprotected keychains in a very secure location, as they contain encryption keys and other credentials.

--iterations=1000: Number of encryption iterations when encrypting the keychain (AES-256). The higher the number of iterations, the harder it is to break the keychain security with brute-force attacks. This inversely increases the time it takes to unlock a protected keychain. The default is 1000 iterations.

Show Keychain 

Synopsis 

cosnim show keychain [KEYCHAIN_OPTIONS] [GLOBAL_OPTIONS]

Description 

Displays the contents of the keychain. For security reasons, the value of the keys is displayed only in the form of hashed values, which helps compare keys with other keychains without disclosing their contents. The cosnim export key command can be used to extract the actual keys``.

Examples 

Display the contents of a keychain

cosnim show keychain --keychain ./mykeychain

Output:

PASSPHRASE_ALGO KEYLEN ITERATIONS KEYCHAIN
--------------- ------ ---------- ----------------------------------------------------
aes pbkdf2      256    1000       ./mykeychain

KEY                            TYPE        SUBTYPE   SIZE HASH
------------------------------ ----------- --------- ---- ----------------------------------------------------------------
default                        encryption  keyblock  4096 62a5b05e60f539d2292b1cd350656b7460bbfd1b109b272a23fc6cb64af9b8ac
james.miller@cosnim.com        private     EdDSA-448 73   257ee3651e136fff287efad8f547c1f4f753a4fba6e8656676e00befcd97cae3
lisa.martinez@cosnim.com       private     RSA-2048  1191 d88bb407ba824a24be894bbe9d7b38dc86c202b736693d7d5378fb2d9708562d
michael.williams@cosnim.com    private     ECDSA-521 241  8a671d1ef8db9ddefa4549a19ca0351ff4db8b0447a70e2683514f0dbe34a646
amazon-s3                      credentials json      117  b23a29ef72a430cc07d739c22f5747455206f5c2c262718d0afc5bbbbe271092

Update Keychain 

Synopsis 

cosnim update keychain [--new-passphrase=PASSPHRASE | --prompt-new-passphrase | -- read-new_passphrase=FILE ] [--iterations=1000] [KEYCHAIN_OPTIONS] [GLOBAL_OPTIONS]

Description 

Modifies the keychain security and, optionally, its passphrase.

Options 

--new-passphrase=NEW_PASSPHRASE: Set a new passphrase to the keychain. Beware that specifying a passphrase as an argument to a command may expose it to interception. --prompt-new-passphrase or --read-new-passphrase are recommended.

--prompt-new-passphrase=NEW_PASSPHRASE: Prompt for a new passphrase to protect the keychain. This is the default.

--read-new-passphrase=FILE: Read the new passphrase from FILE. Beware that any CR, LF or whitespace contained in the file will also be part of the passphrase.

--remove-passphrase: Remove the passphrase from the keychain. This will leave the keychain unencrypted; the file should be strongly protected in other ways.

--iterations=1000: Number of encryption iterations when encrypting the keychain (AES-256). The higher the number of iterations, the harder it is to break the keychain security with brute-force attacks. This inversely increases the time it takes to unlock a protected keychain. The default is 1000 iterations.

generate key 

Synopsis 

cosnim generate key --key=KEYNAME --type=KEYTYPE, [--replace] [KEYCHAIN_OPTIONS] [GLOBAL_OPTIONS]

Description 

Generates an encryption or private key in the keychain. The key is generated using a cryptographically secure random number generator and stored directly in the keychain. Generated keys can be exported with the cosnim export key command.

Options 

--key=KEYNAME: Name to give to the key in the keychain. When generating signature keys, it is recommended to use a recognized email address or distinguished name (DN), as this key name is also what will be displayed to other users when verifying signatures.

--type=KEYTYPE

Type of key to generate. Must be one of the following:

Capsule Encryption Keytypes:

KEYTYPEs

Description

encryption

Cosnim standard encryption key block (4096 bytes).

Digital Signatures Keytypes

KEYTYPEs

Description

EdDSA-255

Fast digital signatures with 128-bit security - recommended

ECDSA-256

Balanced performance and security with 128-bit security

ECDSA-384

Strong 192-bit security, suitable for sensitive data

ECDSA-224

Lower security at 112-bit, used in legacy systems

ECDSA-521

High security with 256-bit equivalent, performance-intensive

EdDSA-448

High-performance signatures with 224-bit security

RSA-2048

Commonly used with 112-bit security for general applications

RSA-3072

128-bit security, more protection but slower than RSA-2048

RSA-4096

Maximum strength with 256-bit security, computationally intensive

--replace: Replace the key if it already exists in the keychain.

Warning

Never replace the ‘default’ encryption key if a continuum has already been created. The default encryption key block is used for other purposes, including capsule naming protection; changing the default key will prevent access to capsules even if those capsules are not encrypted or are encrypted with alternate keys.

export key 

Synopsis 

cosnim export key --key=KEYNAME [--public | --private] [--file=FILE] [KEYCHAIN_OPTIONS] [GLOBAL_OPTIONS]

Description 

Exports a key in an external format so it can be viewed, saved or shared outside of a keychain.

Warning

Always protect exported keys! They are not encrypted when exported. When saving or sharing exported keys, you should encrypt them first. For example, you can use with gpg or openssl to transparently save the exported key in encrypted form without security risks:

cosnim export key --key mykey | openssl enc -e -aes256 -pbkdf2 -out

Options 

--key=KEYNAME: Name of the key to export.

--public: If the key is a signature private key, this exports its public key. The option is ignored for non-PKI keys.

--private: Exports the private key part of a signature. If the key is a PKI public key, the command will fail. Otherwise, the option is ignored for non-PKI keys.

--file=FILE: Name and path of the file into which to write the exported key. If the option is omitted or set to --file=-, the output is written to standard output (stdout).

Examples 

Export the public key associated with a signature private key

cosnim export key --key user.name@company.com --public

Output:

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJAp1AU4WRAldMxu+gzDcgHYDJVpc
OlQiAUdxnk2j36zYVn8ssJiRc0J4JkeMpE30b/RpHXISjeyMbJNwhpZeng==

import key 

Synopsis 

cosnim import key --key=KEYNAME [--file=FILE] [--replace] [KEYCHAIN_OPTIONS] [GLOBAL_OPTIONS]

Description 

Imports a key that was exported from another Cosnim keychain.

Options 

--key=KEYNAME: Name under which the key should be imported.

--file=FILE: Name and path of the file that contains the exported key. If the option is omitted or set to --file=-, the key’s value is read from standard input (stdin).

--replace: Replace the key if it already exists in the keychain.

Warning

Never replace the ‘default’ encryption key if a continuum has already been created. The default encryption key block is used for other purposes, including capsule naming protection; changing the default key will prevent access to capsules even if those capsules are not encrypted or are encrypted with other keys.

delete key 

Synopsis 

cosnim delete key --key=KEYNAME [KEYCHAIN_OPTIONS] [GLOBAL_OPTIONS]

Description 

Delete a key from a keychain.

Options 

--key=KEYNAME: Name of the key to delete. If the key doesn’t exist, an error will be raised.

Filesystem Synchronization & Backups 

sync, backup, restore 

Synopsis 

cosnim sync|backup|restore --profile=PROFILE [FROMPATH TOPATH …] [OPTIONS] [FILTERS] [GLOBAL_OPTIONS]

Description 

The sync command and its variants upload and download files between the native filesystem and Cosnim continuums. It can be used to feed initial data to a continuum, back up and restore existing filesystems on a continuum, and migrate or replicate files to remote locations using a continuum as a transport medium.

The only real difference between the sync, backup, and restore commands is how the FROMPATH and TOPATH parameters are interpreted (see below). Internally, they are all the same operation, and all capabilities, for example, Time-Travel, are equally available whichever command is used.

Sync operations can be customized and automated with ‘sync’ profiles in the configuration file. This reduces the number of options that must be specified in the command.

Options 

sync | backup | restore

Synchronizes files in the following direction:

backup: Copies files from a local filesystem to the continuum. FROMPATHs must all be on the local filesystems and TOPATHs must be on the continuum.
restore: Copies files from the continuum to a local filesystem. FROMPATHS must all be on the continuum and TOPATHs must be on local filesystems.
sync: Copies files from FROMPATHs to TOPATHs without checking the direction.

--profile=PROFILE | --no-profile

Uses a profile from the configuration file to fill in various command options and parameters. This helps to run sync, backup and restore commands quickly and consistently. Options specified on the command line override options read from the profile.

If no --profile option is specified, Cosnim automatically tries to select a profile named ‘sync’, ‘backup’, or ‘restore’ according to the command used. To suppress the automatic selection of a default profile, use the --no-profile option.

FROMPATH TOPATH ...: Specify one or more pairs of source and destination paths. For each pair, one path must be local, and the other must be in the continuum. Local paths must start with a ‘./’ (current directory) or ‘/’ (absolute path). Paths on the continuum must start with ‘cosnim:/’.

--continuous | --continuous-full | --no-continuous

Determines how the command runs.

--continuous activates continuous synchronizations. The command starts with a full synchronization (backup or restore) and then monitors the source for changes. As soon as a file or directory is changed, a targeted sync is immediately triggered to copy the changed files or directories to the destination. This keeps the destination quickly and continuously synchronized with the source. Continuous synchronizations are available on Linux and MacOS systems.

--continuous-full operates similarly to --continuous, except that full resynchronizations are performed whenever changes are detected. This ensures that no change has been missed by the operating system. However, it can significantly increase the time each cycle takes to run. Currently, all supported operating systems report changes correctly to trigger targeted syncs properly, so this option shouldn’t be needed. If additional assurance is desired, consider the --interval option.

--no-continuous cancels any --continuous option that might be specified in the profile.

Note

Note that continuous synchronizations can run in a fraction of a second, sometimes much faster than applications that can create or update files in real time. Although Cosnim has internal mechanisms to detect live activity to ensure full copies, files being updated may still be protected by more than one Time-Travel point, each reflecting the state of the file as it was being saved. When accessing or restoring files at previous time-travel points, it’s a good idea to check if other nearby time-travel points have also been taken, which may reflect a better state of the files.

--interval=SECS: Forces a full resynchronization to run at every SECS seconds. This can be done in parallel or in lieu of continuous synchronizations.

--verify | --no-verify

Determines if file contents are always verified.

When --no-verify is in force (default), Cosnim compares file sizes and modification times to determine if a given file should be copied. If both size and times are equal, Cosnim considers the files equal. This is usually sufficient to detect when files have been modified.

When --verify is specified, Cosnim will re-verify all source files by reading their contents and comparing them to the destination, even if sizes and modification times are identical. This ensures that all files have been perfectly synchronized, but can also significantly increase the time it takes to perform a synchronization, and may incur additional cloud access charges if the continuum is in cloud storage.

--delete | --no-delete

Delete files and directories in the destination that no longer exist in the source. This ensures that the destination remains an identical copy of the source. The default is --delete. When the destination is a continuum, note that even if files or directories are deleted with this option, the original files and directories remain fully protected by Time-Travel.

To keep files and directories in the destination even if they no longer exist in the source, specify --no-delete, or use one or more --ignore filters to exclude paths from consideration.

--delete-pacing=TIME

Specifies how long it takes to wait for files to remain deleted from the source before considering them actually deleted. The time can be specified as a number of seconds or any time units (for example, ‘500 ms’). The default --delete-pacing is 500ms.

Delete pacing is particularly important during continuous syncs when applications may use filesystem rename & delete operations to save files. Without pacing, Cosnim will often detect the rename or deletion while the application is still running, which will cause the file to appear deleted and recreated in the destination. By pacing deletions this gives time to the application to complete its rename/delete cycle, ensuring that the file on the destination is recorded as having been updated instead of being deleted & recreated.

--drift-ns=NANOSECONDS

The --drift-ns parameter allows file modification times to differ by up to NANOSECONDS without triggering a sync. This addresses timestamp resolution differences between filesystems.

Different filesystems store modification times with varying precision:

Filesystem	Resolution	Recommended --drift-ns (select the highest)
APFS	1 nanosecond	1
Btrfs	1 nanosecond	1
EXT2	1 second	1000000000
EXT3	1 second	1000000000
EXT4	1 nanosecond	1
FAT	2 seconds	2000000000
HFS+	1 second	1000000000
NTFS	100 nanoseconds	100
ReiserFS	1 second	1000000000
ZFS	1 nanosecond	1
exFAT	10 milliseconds	10000000

When synchronizing between filesystems, use the highest drift value from the filesystems involved. For example:

NTFS ↔ FAT32: use --drift-ns=2000000000 NTFS ↔ ext4: use --drift-ns=100 ZFS ↔ HFS+: use --drift-ns=1000000000

This prevents unnecessary file copies caused by timestamp precision differences rather than actual content changes.

--timetravel-tag=PREFIX

Use the string PREFIX to tag time-travel points after each sync cycle. The default is to use the command name, title-cased, as prefix (‘Sync’ or ‘Backup’).

Time-Travel tags help differentiate backup and upload events in Time-Travel more clearly. They are the equivalent of an incremental backup, differential backup, full backup and instant snapshot all in one.

--stats, --all-stats, --no-stats: Determines when synchronization statistics, such as the number of files examined and copied, are to be reported. --stats reports statistics whenever files were copies (the default), --all-stats reports statistics even if no files were copied, and --no-stats suppresses statistics. The default is --stats.

--mount | --mount-ro | --mount-rw | --no-mount: Determines if the continuum filesystem should be mounted while synchronization is active. --mount and --mount-ro automatically mounts the filesystem in read-only mode, --mount-rw mounts the filesystem in read-write mode (not recommended), and --no-mount suppresses mounting the filesystem.

-n, --dry-run: Simulate a synchronization, reporting how files would be synchronized without actual data movement. At the moment, dry-runs are available only when synchronizing to the continuum (uploads & backups).

Configuration Commands 

Show Config 

Synopsis 

cosnim show config [--format=yaml|json] [GLOBAL_OPTIONS]

Description 

Displays the configuration file and its inclusions. This can be useful to examine the entire configuration parameters that Cosnim will use.

Options 

--format=yaml|json: Select the format of the configuration parameters. The default is ‘yaml’.

Check Config 

Synopsis 

cosnim check config

Description 

Reads and verifies that the configuration file syntax is valid.

Storage and Hubs Management 

show hubs 

Synopsis 

cosnim show hubs [-l, --long] [GLOBAL_OPTIONS]

Description 

Displays the currently configured storage hubs and their hierarchy.

Options 

-l, --long: Also display the hub’s current internal states. This is used mainly for support.

Examples 

Display All Hubs and Their Internal States*

cosnim show hubs

Output:

NODE_NAME       NODE_TYPE STORAGE_UUID
--------------- --------- ------------------------------------
primary         typed
+-- system      scatter
    +-- system1 capsules  e14d665f-e3e4-46fd-a88c-b643a9b628b9
    +-- system2 capsules  85a51af4-ad89-4e19-91cc-743a27fdc462
    +-- system3 capsules  a5e9c68d-3a1d-4690-8e39-bf3901583fb8
+-- meta        scatter
    +-- meta1   capsules  34c6333b-ce42-4ea0-8f54-f1541709372a
    +-- meta2   capsules  d9a46b8a-2928-4f6e-932f-0ebedf3f3efe
    +-- meta3   capsules  cd223688-b627-4218-9c80-32a1f0f8f4be
+-- data        scatter
    +-- data1   capsules  763867d9-3e5c-429e-a305-8b9bdd8cc4ce
    +-- data2   capsules  835c7772-f392-48c2-bd23-01a4854f7879
    +-- data3   capsules  f00e2d39-d971-4b03-bed2-e516b1fac23a
    +-- data4   capsules  662710c3-a22a-4db0-94fa-1d25d8de4549
    +-- data5   capsules  9b86afb1-9750-4907-a1be-a0712686e321

drain hub 

Synopsis 

cosnim drain hub --hub=HUBNAME [--limit=NUMBER]

Description 

Drains capsules from a storage hub. This causes the capsules to be moved to other storage hubs according to the configuration’s configuration and replication policies. Use this command in preparation to decommission a storage hub or to reduce its load.

Note

It is not necessary to use this command to copy or migrate capsules in storage hubs. You may also directly copy and move capsules in raw storage with any tool that is able to access physical storage. Cosnim instances will automatically detect the background movements and adapt dynamically to the changes.

Options 

--hub=HUBNAME: Name of the hub Also display the hub’s current internal states. This is used mainly for support.

--limit=NUMBER: Only drain up to NUMBER of capsules and then stop. This is useful to pace migrations or partially relieve pressure on a storage system without draining all capsules.

reset fingerprints 

Synopsis 

cosnim reset fingerprints [GLOBAL_OPTIONS]

Description 

Resets storage hubs’ fingerprints. This may be necessary if some backend storage system has been moved, altered or recovered.

About fingerprints 

Fingerprints are used to check physical storage consistency. They are generated from stable storage information such as data center location, bucket name, filesystem paths and physical configuration metadata that is not expected to change with time. However, fingerprints may in some circumstances change after major events such as physical storage recovery or important data manipulations such as altering a cloud storage bucket’s name or local storage physical path.

To ensure integrity, Cosnim will refuse to connect to storage hubs when fingerprints change, as this may be a warning sign that the physical storage may have been manipulated or duplicated inconsistently. To resume operations, use the reset fingerprint to confirm to Cosnim that the storage manipulation was legitimate and that it may use the newly reconfigured storage.

Warning

Do not reset fingerprints if you are uncertain why the underlying storage’s fingerprint has changed. In case of doubt, double-check the storage hub’s configuration and storage system to confirm this is still the same storage as before.

Time-Travel Commands 

show timetravel 

Synopsis 

cosnim show timetravel [OPTIONS] [GLOBAL_OPTIONS]

Description 

Displays timetravel information for the current continuum.

Note

The command-line interface to Time-travel is provided only for convenience. To fully experience Time-Travel: please mount and browse a continuum as a filesystem; this will give you full access to all Time-Travel information in a much more user-friendly and tools-friendly fashion than the CLI.

Options 

-f, --files: Display all files that were altered at each time-travel point. The default is to display only the time-travel points themselves.

--dirs: Also display intermediary directory update events. Directory update events are typically reported only if they have significance, such as creating, deleting or altering the attributes of a directory, but are otherwise suppressed when the activity was to record a file being added, updated or deleted since that is already reported with the --files option.

-l, --long: Display detailed file and directory information in addition to the name, such as owner IDs and permission bits. This is equivalent to the -l,--long option to ls commands on Posix systems.

--capsules: Show the capsule that contains related time-travel information and its location. This can be used to determine how time-travel information is distributed in storage hubs.

--tags: Show the time-travel tags (aka snapshots) associated with the time-travel points. This is the default.

--no-tags: Don’t display the associated time-travel tags (snapshots).

--tagged: Only display time-travel points that have been tagged, for example, by the cosnim sync command. This is the default.

--all: Display all high-level internal time-travel points, whether they are tagged or untagged. Beware that internal time-travel points work at high resolution and will frequently capture in-flight updates. For example, saving a Microsoft Office document is often recorded in multiple time-travel points due to Office’s relatively slow speed compared to time-travel protection. When choosing a time-travel point to examine a file, directory or continuum state, consider the other time-travel points created around that time to determine which one best represents the precise state you are truly interested in.

show versions 

Synopsis 

cosnim show versions PATH [-l, --long] [--limit=NUMBER] [GLOBAL_OPTIONS]

Description 

Display all the versions of a given file or directory.

Options 

PATH: Path of the file or directory to obtain time-travel information relative to the continuum’s filesystem root.

-l, --long: Display additional information about the files and directories.

--limit=NUMBER: Limit the number of versions displayed, starting from the most recent version. This option is useful for files and directories that may have a very long history.

Algorithms 

The following commands display, test and measure the performance of various algorithms on the current system. This can be useful when analyzing and determining which algorithms to use in a configuration.

Note

Performance results can vary significantly due to many factors, such as the machine’s processor architecture, the load on the system, the operating system being used, the virtualization platform, the libraries installed and the size of the data. If performance is an important criterion, you should repeat these tests multiple times on all platforms before finalizing your choice, and of course consider other aspects, such as the algorithm’s security and robustness, which is beyond the purpose of these commands.

test hashes 

Synopsis 

cosnim test hashes [-l, --long] [--sort=COLUMNS] [GLOBAL_OPTIONS]

Description 

Test and display checksum and cryptographic hashing algorithms on the current platform.

Options 

-l, --long: Display full information about each hash algorithm and its results.

--sort=SORT

Sort the results based on one or more columns. Add ‘:a’ or ‘:d’ to column names to sort by ascending or descending order. If sorting by multiple columns, separate column names with semicolons (;). Examples:

SORT	Results
mb/s	Sort by performance, from slowest to fastest
mb/s:d	Sort by performance, from fastest to slowest (descending)
type;mb/s:d	Sort type hash type then by descending performance

Examples 

Test available hashing algorithms, sorted by type and performance.
```
cosnim test hashes -l --sort 'type;mb/s:d'
```

Output:

LIBRARY   ALGORITHM     TYPE      BITS     MB/S  SIZE-KB  COUNT       CPU      TIME  ERROR
--------  ------------  --------  ----  -------  -------  -----  --------  --------  -----
zlib      crc32         checksum    32  42000.0   1638.0      1  0.000038  0.000039  -
zlib      crc32         checksum    32  23400.0     16.4    100  0.000069  0.000070  -
zlib      adler32       checksum    32  21000.0   1638.0      1  0.000077  0.000078  -
zlib      adler32       checksum    32  16380.0     16.4    100  0.000100  0.000100  -
zlib      crc32         checksum    32   6525.9      1.6   1000  0.000250  0.000251  -
zlib      adler32       checksum    32   5515.2      1.6   1000  0.000297  0.000297  -
hashlib   sha1          crypto     160   3120.0   1638.0      1  0.000525  0.000525  -
hashlib   sha224        crypto     224   3120.0   1638.0      1  0.000525  0.000525  -
hashlib   sha256        crypto     256   3120.0   1638.0      1  0.000525  0.000525  -
hashlib   sha256        crypto     256   2983.6     16.4    100  0.000548  0.000549  -
hashlib   sha1          crypto     160   2930.2     16.4    100  0.000555  0.000559  -
hashlib   sha224        crypto     224   2833.9     16.4    100  0.000578  0.000578  -
hashlib   sha256        crypto     256   2210.5      1.6   1000  0.000738  0.000741  -
hashlib   sha224        crypto     224   2204.6      1.6   1000  0.000744  0.000743  -
hashlib   sha1          crypto     160   2201.6      1.6   1000  0.000742  0.000744  -
hashlib   sha512        crypto     512   1830.2   1638.0      1  0.000894  0.000895  -
hashlib   sha384        crypto     384   1826.1   1638.0      1  0.000894  0.000897  -
hashlib   sha512        crypto     512   1772.7     16.4    100  0.000923  0.000924  -
hashlib   sha384        crypto     384   1757.5     16.4    100  0.000927  0.000932  -
hashlib   sha512        crypto     512   1459.9      1.6   1000  0.001120  0.001122  -
hashlib   sha384        crypto     384   1447.0      1.6   1000  0.001128  0.001132  -
hashlib   shake128-256  crypto     256   1406.0   1638.0      1  0.001161  0.001165  -
hashlib   shake128      crypto     128   1404.8   1638.0      1  0.001163  0.001166  -
hashlib   shake128-256  crypto     256   1348.1     16.4    100  0.001214  0.001215  -
hashlib   shake128      crypto     128   1319.9     16.4    100  0.001240  0.001241  -
hashlib   sha3-224      crypto     224   1209.7   1638.0      1  0.001350  0.001354  -
hashlib   sha3-224      crypto     224   1157.6     16.4    100  0.001412  0.001415  -
hashlib   shake256-512  crypto     512   1145.5   1638.0      1  0.001429  0.001430  -
hashlib   sha3-256      crypto     256   1144.7   1638.0      1  0.001430  0.001431  -
hashlib   shake256      crypto     256   1143.1   1638.0      1  0.001429  0.001433  -
hashlib   sha3-256      crypto     256   1112.8     16.4    100  0.001468  0.001472  -

test encryption 

Synopsis 

cosnim test encryption [-l, --long] [--cycles=CYCLES] [--sort=COLUMNS] [GLOBAL_OPTIONS]

Description 

Test and display encryption algorithms on the current platform.

Note

Encryption algorithms frequently exploit special CPU instructions to increase their speed. Their performance will, therefore, vary significantly from one platform or machine model to another. CPU instructions may also affect the performance of algorithms on large data sets versus small data sets.

If using this command to determine the fastest algorithm available, run it on all applicable platforms, especially when running in the cloud. If in doubt, consider AES-256-CBC, which is generally known to give the best overall performance on all platforms and data set sizes despite not always being the fastest algorithm.

Options 

-l, --long: Display complete information about each hash algorithm and its results.

--cycles=CYCLES: Number of global test cycles to run. The default is 1. Running more cycles can help average out the results but will take longer to run.

--sort=SORT

Sort the results based on one or more columns. Add ‘:a’ or ‘:d’ to column names to sort by ascending or descending order. If sorting by multiple columns, separate column names with semicolons (;). Examples:

SORT	Results
mb/s:d	Sort by performance, fastest first (default sort order)
operation;size-kb:d	Sort by encryption/decryption operation and data set size

Examples 

Test all encryption algorithms, sorted by data set size and performance
```
cosnim test encryption --sort operation;size-kb;mb/s
```

Output:

ALGORITHM    OPERATION   MB/S  SIZE-KB  ERROR
-----------  ---------  -----  -------  -----
chacha20-12  Decrypt    714.5   1632.0  -
chacha20-12  Decrypt    642.3     16.3  -
aes-192-cbc  Decrypt    343.0   1632.0  -
aes-256-cbc  Decrypt    341.8   1632.0  -
aes-128-cbc  Decrypt    337.6   1632.0  -
aes-256-ctr  Decrypt    334.6   1632.0  -
aes-128-ctr  Decrypt    332.0   1632.0  -
aes-192-ctr  Decrypt    330.4   1632.0  -
chacha20-12  Decrypt    321.1      1.6  -
aes-256-cbc  Decrypt    317.2     16.3  -
aes-192-cbc  Decrypt    316.2     16.3  -
aes-128-cbc  Decrypt    312.8     16.3  -
aes-256-ctr  Decrypt    297.3     16.3  -
aes-192-ctr  Decrypt    296.9     16.3  -
aes-128-ctr  Decrypt    294.5     16.3  -
aes-192-ocb  Decrypt    265.0   1632.0  -
aes-256-ocb  Decrypt    264.1   1632.0  -
aes-128-ocb  Decrypt    263.7   1632.0  -
aes-128-siv  Decrypt    199.2   1632.0  -
aes-256-siv  Decrypt    198.8   1632.0  -
aes-192-siv  Decrypt    198.3   1632.0  -
aes-192-ocb  Decrypt    196.0     16.3  -
aes-256-ocb  Decrypt    195.7     16.3  -
aes-128-ocb  Decrypt    193.3     16.3  -
aes-128-gcm  Decrypt    187.0   1632.0  -
aes-256-gcm  Decrypt    186.3   1632.0  -
aes-192-gcm  Decrypt    185.6   1632.0  -
aes-256-cbc  Decrypt    166.9      1.6  -
aes-192-cbc  Decrypt    166.5      1.6  -
aes-128-cbc  Decrypt    165.7      1.6  -
aes-256-ctr  Decrypt    149.1      1.6  -
aes-192-ctr  Decrypt    148.9      1.6  -

test signatures 

Synopsis 

cosnim test signatures [-l, --long] [--cycles=CYCLES] [--sort=COLUMNS] [GLOBAL_OPTIONS]

Description 

Test and display digital signature algorithms on the current platform.

Options 

-l, --long: Display complete information about each hash algorithm and its results.

--sort=SORT

Sort the results based on one or more columns. Add ‘:a’ or ‘:d’ to column names to sort by ascending or descending order. If sorting by multiple columns, separate column names with semicolons (;). Examples:

SORT	Results
mb/s	Sort by performance, from slowest to fastest
mb/s:d	Sort by performance, from fastest to slowest (descending)
size;mb/s:d	Sort by data size and then by descending performance

Examples 

Test available signature algorithms, sorted by performance (default)
```
cosnim test signatures
```

Output:

SCHEME     BITS  SIGNATURE-SIZE  SIGNATURES/S  VERIFY/S  SPECIFICATION                         ERROR
---------  ----  --------------  ------------  --------  ------------------------------------  -----
EdDSA-255   255              64        4708.1    1623.9  EdDSA-255-Ed25519-RFC8032-SHA512      -
ECDSA-256   256              64        4681.6    2094.7  ECDSA-256-secp256r1-RFC6979-SHA256    -
ECDSA-384   384              96        2638.5     819.5  ECDSA-384-secp384r1-RFC6979-SHA384    -
ECDSA-224   224              56        2079.4    1401.0  ECDSA-224-secp224r1-RFC6979-SHA224    -
ECDSA-521   521             132        1684.6     615.3  ECDSA-384-secp521r1-RFC6979-SHA512    -
EdDSA-448   448             114         845.0     403.9  EdDSA-448-Ed448-RFC8032-SHAKE256-512  -
RSA-2048   2048             256         413.8    2722.6  RSA-2048-PSS-MGF1-32-SHA256           -
RSA-3072   3072             384         156.2    1401.7  RSA-3072-PSS-MGF1-48-SHA384           -
RSA-4096   4096             512          77.4     888.9  RSA-4096-PSS-MGF1-64-SHA512           -

Note

If analyzing signature algorithms, take into consideration the algorithm’s actual strength, which can be more important than the key size used.

test rindex 

Synopsis 

cosnim test rindex --file=FILE [-l, --long] [GENERAL_OPTIONS]

Description 

Test and display the results of the randomness/ransomware index (rindex) algorithm on some user data.

About the rindex 

The rindex is a computed value between 1 and 100 that indicates the relative randomness of data, with higher values indicating higher randomness. It is calculated automatically by Cosnim on all data fragments whenever data is stored or updated in a continuum. It can be used, for example, to detect ransomware encryption attacks on existing data or, to a certain degree, indicate the compressibility of data. Rindex values are recorded automatically in Time-Travel and inviolable audits as the same time data is written in a continuum, making it a highly secure, confidential and fast source of information that can be analyzed and extracted without accessing the data itself.

This command helps map out typical rindex values generated for various pieces of data, facilitating the interpretation of rindex values found in a continuum. Take note that Cosnim calculates rindex values on data fragments, not entire files, so the results of this command may differ slightly from those stored in a continuum.

Options 

--file=FILE: Name of the file containing data for which an rindex value is to be calculated.

-l, --long: Display additional algorithm information. This information is primarily helpful for Cosnim support personnel.

Software and Diagnostics 

show version 

Synopsis 

cosnim show version [-l, --long]

Description 

Displays the current software version. This may also be accomplished with the --version general option.

Options 

-l, --long: Display additional information about the software version.

Examples 

Display Short Version

cosnim show version

Output:

Cosnim Nexus version 0.7.3, build 1840

Display Long Version Information

cosnim show version --long

Output:

PRODUCT      VERSION   PLATFORM BUILD DATE                    STAMP
------------ --------- -------- ----- ----------------------- ----------------------------------------
Cosnim Nexus 0.7.3     Darwin   1840  2024-10-05 23:10:36 EDT 1252eb0801298c4e1c6c004984a228d62c6b1bc5

check license 

Synopsis 

cosnim check license

Description 

Verify the validity of the current software license and display some of the restrictions and features available with this license.

Beware that licensing terms may include other restrictions that are not displayed or thoroughly checked by this command, such as hostname, machine count and actual storage used.

Example 

cosnim check license

Output:

LICENSED TO                                         VALID UNTIL              CAPACITY   FEATURES
--------------------------------------------------  -----------------------  ---------  --------------------------
Acme Corporation, 1 Software av., Westlake, GN      2025-10-24 00:00:00 UTC  100.00 TB  backup, vault, nexus, full

The above confirms that Acme Corporation has access to all Cosnim features on this machine until October 2025, with a total storage capacity of 100TB. Beware that licensing terms may include other restrictions not displayed by this command, such as hostname and machine count restrictions. This command confirms that the software will run licensed on the current machine.

Diagnostic Commands 

Synopsis 

cosnim diagnostic [SUBCOMMAND] [--help] [OPTIONS] [GLOBAL_OPTIONS]

Description 

Execute internal diagnostic commands. These are typically used under the direction of support personnel. If your license permits, you may already have access to diagnostic commands, in which case help on diagnostic commands is available with the --help option.

Warning

Diagnostic commands may produce massive outputs, stress shared storage access, and incur significant cloud access charges if misused.