Volumes

Once you have set up syntool, you can use it to create and manage your Volumes.

A Volume is a lot like a virtual disk. You pick which cloud storage and CDNs will host file data and metadata, and you pick which users can access it. A file and directory belongs to exactly one Volume, and its blocks will be stored on that Volume's cloud storage providers and delivered by that Volume's cache providers.

The Volume API

You use syntool.py to access the Volume API. The following methods are supported:

create_volume
read_volume
update_volume
delete_volume
list_volumes
list_accessible_volumes
list_public_volumes
list_archive_volumes
set_volume_public_signing_key
request_volume_access
set_volume_access
remove_volume_access_request
list_volume_access_requests
list_user_access_requests

You can pull up the list of arguments and their meanings with

$ syntool.py help [method name]

Creating a Volume

You use the create_volume method to create Volumes. At a minimum, you'll need your username, the name of the Volume, the description of the Volume, and the block size. For example, the command

$ syntool.py create_volume $SYNDICATE_USER_ID HelloWorld "This is my first Volume, called HelloWorld" 122880 default_gateway_caps=ALL

will create a Volume called HelloWorld, with a block size of 120KB. Any gateway you create will receive every access capability by default (as set by default_gateway_caps). Replace $SYNDICATE_USER_ID with your Syndicate user ID. Run syntool.py help create_volume for more Volume creation details.

Volume Access Control

To let someone else access your Volume, simply have them make a request with syntool. For example, to request read-only access to a Volume called HelloWorld, the requester would issue a command similar to this one:

requester:$ syntool.py request_volume_access $REQUESTER_USER_ID HelloWorld READONLY "Please give me access to your Volume."

($REQUESTER_USER_ID is the requester's Syndicate user ID).

Then, you can see the pending access requests with the command.

you:$ syntool.py list_volume_access_requests HelloWorld

To add the requester to HelloWorld, with read-only capabilities, you can do so with this command:

you:$ syntool.py set_volume_access $REQUESTER_USER_ID HelloWorld READONLY

Now, the requester will have read-only access to HelloWorld. You can revoke it later with:

you:$ syntool.py remove_volume_access_request $REQUESTER_USER_ID HelloWorld

Remarks

A block is the smallest amount of data that will be fetched by an HTTP request. Since gateways will read, write, and cache file data by the block, it's good to use a reasonably large block size to ensure you have acceptable goodput. We recommend at least 120KB, or even larger (in the MBs) if you're going to be dealing with large files, especially read-only files (like images, movies, or datasets).

In addition to the usual access keys, each Volume has a public key (the metadata public key) that will be used by gateways to verify the authenticity of Volume directory information. You can give this key to your gateways out of band, or have them automatically download it on first run. The MS keeps the associated private key.