Quick Start

Use this guide to quickly get Cosnim up and running for the first time.

Initial Setup

This is how the directory where you will install and run Cosnim in this quick guide will look like:

| └── cosnim
|     ├── bin
|     ├── config
|     ├── capsules
|     └── mount

If you haven’t done so yet, create a cosnim directory and install the software in the ‘bin’ directory:

mkdir cosnim
cd cosnim
mkdir bin
tar -xf Cosnim...tar.gz -C bin/

Note

You don’t have to install Cosnim in the ‘bin’ directory. This is only suggested to make quick setups simpler. You are free to install Cosnim anywhere you want.

Activate the cosnim command:

Cosnim is automatically activated during installation. You don’t need to take any special action.

Create an initial configuration using the sample:

mkdir config
cp bin/samples/config.yml config/

Install your licence key:

cp path/to/your/downloaded/license.key config/

Generate a keychain and the encryption keys that will protect your data in physical storage:

cosnim create keychain --no-passphrase

Note

The first time you run Cosnim, you may experience some substantial delay. This is normal and due to OS security verifications. Subsequent executions will not incur such a delay.

If you want to protect your keychain with a passphrase, which will be prompted for every time you run a cosnim command, omit the --no-passphrase option above, or update your keychain with the command:

cosnim update keychain --prompt-passphrase

Create a Continuum

The sample configuration file automatically uses your local disk under the current capsules/ directory as primary storage. To create a local continuum, run the command:

cosnim create continuum

The continuum is now ready to hold data.

Backup Data

To use Cosnim as a backup system, run a cosnim backup command with some of your files:

cosnim backup -vv path/to/your/local/files cosnim:/Backups/myfiles

The above will copy all the files under path/to/your/local/files to the continuum under the directory Backups/myfiles and then stop.

To run Cosnim backups in continuous mode, add the --continuous option. You can run this in a separate terminal or window:

cosnim sync -vv --continuous path/to/your/local/files cosnim:/Backups/myfiles

Update your local files

This is an excellent time to update some of your local files while Cosnim is running continuous backups so it can pick up your changes and record them in Time-Travel. Do a few updates so you have interesting data. Cosnim should instantly detect each update and back up your data immediately to the continuum after each update.

If you wish to customize the backup command, you may update the ‘sync_profiles/backup’ section in the configuration file config.yml, where you can specify paths to backup, filters and various options. You’ll then be able to run backups more simply with the command:

cosnim sync -vv --continuous

Mount As a Live Filesystem

To use Cosnim as a live filesystem, mount it with:

cosnim mount

You now have direct access to the continuum as a live filesystem. If you previously ran backups, you’ll also see your backups there.

Exploring Time-Travel

Whether you use a continuum for backups, vaulting or as a live filesystem, Time-Travel faithfully protects your data as if you had automatic full version history, continuous backups, auditing, and snapshots all-in-one.

To explore Time-Travel when using Cosnim as a live filesystem, first mount your continuum with the command:

cosnim mount

If you are using Cosnim for continuous backups, you should instead mount your filesystem with the --mount option or the cosnim backup command:

cosnim backup -vv --continuous --mount

Current State

You can browse the current state of the continuum at the mountpoint, which is located under ./mounts/test-1 in the sample configuration. If running under MacOS, you’ll also see your continuum as a “Cosnim Continuum” volume. In both cases, you’ll have access to the entire contents of your continuum, including the latest backup, if applicable.

Browsing Time-Travel

There are multiple ways of exploring Time-Travel. They all involve the use of hidden virtual files and directories containing the string ~~~. You won’t see them by listing or browsing directories. You need to open them explicitly.

If you’re using MacOS, you can use the “Cosnim Inspect” Quick Action by right-clicking on the “Cosnim Continuum” volume icon on the desktop or computer sidebar and select the menu “Quick Actions -> Cosnim Inspect”. On Linux and command-line environments, browse the hidden directory “~~~” under the mountpoint, for example, ./mounts/test-1/~~~. In both cases, this will show you various files and directories you can explore. The following sections explain more about the multiple ways you can leverage Time-Travel.

Note

All the special “~~~” Time-Travel files, directories, web pages and documents are purely virtual. They don’t exist for real. They are generated on the fly upon request. Most of them will respond instantly, but you may find some of them may have a slight delay if your continuum has grown a lot or contains a very high amount of Time-Travel points.

Continuum-level Time-Travel

Time-Travel at the continuum level is somewhat similar to traditional snapshots (except they are much faster and more frequent). You’ll see the entire contents of your filesystem at each Time-Travel point in time.

There are two ways you can explore Time-Travel at the continuum level:

  • Through the ~~~Timetravel special directory under the mountpoint (ex: ./mounts/test-1/~~~Timetravel, or Finder quick action = “Cosnim Time-Travel”). This will show you all discrete Time-Travel points in a hierarchy of directories starting with the year, month-day, hour-minute, and finally, each distinct time-travel point.

  • Through the ~~~Snapshots special directory under the mountpoint (ex: ./mounts/test-1/~~~Snapshots, or Finder quick action = “Cosnim Snapshots”). The result is similar to Time-Travel points, except that Snapshots only show you the Time-Travel points that were tagged after each backup cycle. You’ll find the snapshots more practical when exploring the results of cosnim backup.

After opening up a few depths of directories, you’ll reach a list of Time-Travel points, such as:

2023-12-14@01.13.03.138682880EDT~~~^3mrqtpvm3l2w
2023-12-14@01.13.09.283315968EDT~~~^68klmlkv1388
2023-12-14@01.13.17.251356928EDT~~~^6rc4w3k33lew

These reflect the state of the entire continuum at each of those points. Open each of those directories to explore all of the data that existed in the continuum at that time.

Warning

If you use deep-level scanning tools such as find, tree and grep -r, do that only inside actual Time-Travel points. If you run these tools on upper Time-Travel directories, such as on a year or month-day, the tools will repeatedly explore each of the Time-Travel points as full individual filesystems, which can take a long time and needlessly generate huge amounts of information.

Directory and File-level Time-Travel

To explore Time-Travel at the directory and file level, open a directory named after the file or directory you wish to explore, followed by “~~~”. For example:

./mounts/test-1/mydir/filea.txt~~~

This will open up a subdirectory with various Time-Travel information, including a “Versions” directory that, if you open it, will show you all the past versions of that file. You can access those Versions directly by appending “~~~Versions” to the file or directory you want to examine. For example, if you want to see all the versions of the file mydir/filea.txt, open the directory:

./mounts/test-1/mydir/filea.txt~~~Versions

This will show a listing of file versions such as:

-rwx------@ 1 guy  staff  5352 21 Dec 13:39 filea~~~^3dnl2tth3vey.txt
-rwx------@ 1 guy  staff  5347 21 Dec 13:39 filea~~~^3jdqw3jr0gdl.txt
-rwx------@ 1 guy  staff  5360  7 Dec 02:06 filea~~~^3m8n2zk48gj3.txt

You can read each of these files as if they were regular files and see their contents exactly as they existed at that precise time.

Note

Time-Travel runs internally at a very high frequency and may capture transitory states of files as they are being re-written or updated by software. Although these transitory Time-Travel points don’t consume additional storage, they sometimes may reflect files in incomplete states. If you see multiple Time-Travel file versions very close to one another, for example, within the same second, choosing the latest one is usually best.

You can similarly explore the past versions of a directory. Note that Time-Travel on a directory only shows you the past states of this particular directory. If you open subdirectories under this directory, it will show you the current state of that subdirectory. To explore the entire hierarchy of a directory and subdirectories at a fixed point in time, use continuum-level Time-Travel.

Audits

To obtain detailed auditing information about changes that occurred in files, directories, or Time-Travel points, look at files named Audit.* under the Time-Travel explorer (“~~~”), or use the “Cosnim Audit” Finder Quick Action.

For example, to view auditing information about the previous filea.txt above in HTML format, you can view it with either of the following paths:

open ./mounts/test-1/mydir/filea.txt~~~Audit.html
open ./mounts/test-1/mydir/filea.txt~~~/Audit.html

Along with audits, you’ll also find various files that give other insights into the state of the file, such as the old and new contents, signature verification, etc. All of this information is purely virtual. It is generated on the fly from analyzing Time-Travel states in various formats, so feel free to use whatever format suits your needs best.

What’s next

This was a quick guide designed to get you up and running very quickly on your own. Please refer to the remaining documentation for information on how to configure and use Cosnim most effectively.