Managing File Systems

The s3qladm command performs various operations on unmounted S3QL file systems. The file system must not be mounted when using s3qladm or things will go wrong badly.

The syntax is

s3qladm [options] <action> <storage-url>

where action may be either of passphrase, restore-metadata, clear, recover-key or upgrade.

The s3qladm accepts the following general options, no matter what specific action is being invoked:

--authfile <path>

Read authentication credentials from this file (default: /home/nikratio/.s3ql/authinfo2).

--backend-options <options>

Backend specific options (separate by commas). See backend documentation for available options.

--cachedir <path>

Store cached data in this directory (default: /home/nikratio/.s3ql).

--max-connections <no>

Maximum number of concurrent backend I/O operations (default: 32). This is independent of –max-threads, which governs compression.

--max-threads <no>

Number of parallel compression/encryption threads to use (default: auto). This bounds CPU parallelism only and is independent of –max- connections.

--debug

Activate debugging output from all S3QL modules. Debug messages are written to the destination given by –log.

--debug-modules <module>

Activate debugging output from the named module. May be given multiple times; use ‘all’ for everything. Debug messages are written to the destination given by –log.

--quiet

be really quiet

--install-completion

Install completion for the current shell.

--show-completion

Show completion for the current shell, to copy it or customize the installation.

--help

Show this message and exit.

Changing the Passphrase

To change the passphrase of a file system, use the passphrase subcommand:

s3qladm passphrase  <storage url>

This will not actually re-encrypt all the stored data with the new passphrase. Rather, S3QL generates an internal “master key” when the file system is created and uses this key to encrypt all stored data. The user-supplied passphrase is used to encrypt/decrypt only the master key, and can therefore be changed. This means, however, that if a passphrase has been disclosed to someone untrusted, changing it afterwards will not revoke access to people who had access to the old passphrase (because they could have decrypted the master key and retained a copy).

Recovering the master key

If you’ve been extremely unlucky, then it is possible that a bug in S3QL or data-loss by your storage provider has resulted in object that holds the filesystem master key becoming inaccessible. In this case, knowing the passphrase does not help, as there is no master key to decrypt with it.

If you have also been diligent, then you can restore the master key from the external copy that mkfs.s3ql has asked you to make on filesystem creation time:

s3qladm recover-key <storage url>

Restoring Metadata Backups

If the most-recent copy of the file system metadata has been damaged irreparably, it is possible to restore one of the automatically created backup copies.

The command

s3qladm restore-metadata <storage url>

will give you a list of the available metadata backups and allow you to select one to restore.

Warning

You should probably not use this functionality without having asked for help on the mailing list first (see Further Resources / Getting Help).

Deleting a file system

A file system can be deleted with:

s3qladm clear <storage url>

This physically deletes all the data and file system structures.

Recovering unused space

When deleting files and directories, the corresponding space in the metadata database is not immediately reclaimed but marked as free and reused when new directory entries are created. To reclaim this space, and reduce the size of the metadata file on disk and in the backend, you can run:

s3qladm shrink-db <storage url>

Upgrading the file system

If you have installed a new version of S3QL, it may sometimes be necessary to upgrade the file system metadata as well. After this operation, the file system can no longer be accessed with older versions of S3QL.

During the upgrade you have to make sure that the command is not interrupted, and that no one else tries to mount, check or upgrade the file system at the same time.

To upgrade a file system from the previous to the current revision, execute

s3qladm upgrade <storage url>