Download Command-Line API Tools

Go2Cloud provides ready made command line tools so you can control your cloud infrastructure without writing any code. They are shell scripts for Linux, Unix, and Cygwin on Windows.

Where to get them

You need to be logged in to download the scripts. They are linked from your profile page, under API Tools, along with your own endpoint and authentication details:

• JHB1 profile page
• JHB2 profile page

There are three scripts:

Use the column for the site your account is on. Always take the scripts from here rather than reusing an older copy, so you have the current version.

Installing

Save the scripts somewhere convenient and make them executable:

chmod +x go2cloud.sh go2cloud-upload.sh go2cloud-download.sh

You need bash 4.2 or newer, curl, and GNU coreutils. On Cygwin, install the curl, gzip and coreutils packages, which are not part of the Cygwin base install. The scripts run on Linux, on Windows Subsystem for Linux, and on Cygwin. They are not supported on macOS or BSD, whose dd lacks the options the scripts need.

If you open the scripts in a Windows text editor and save them, they may pick up Windows line endings and refuse to run. Run dos2unix on them to fix this.

Getting started

Run any of the scripts from a terminal with no arguments and it will guide you through the rest, including which datacentre your account is in and where to find your credentials:

./go2cloud-download.sh

Nothing is saved to your machine. Your credentials apply to that run only.

If you prefer to set them yourself, copy both lines from your profile page under API Tools and paste them into your terminal. They then apply to every command in that terminal session:

export G2CURI=https://api-jhb1.go2cloud.co.za
export G2CAUTH=<account-uuid>:<api-key>

Use api-jhb2.go2cloud.co.za if your account is in JHB2. Your profile page shows the correct value for your account.

If you are on a very old Unix system that exposes environment variables to other users through ps, you can leave the secret key off the end of G2CAUTH. curl will then prompt you for it.

Transfers that survive interruptions

Large images are uploaded and downloaded in chunks, with progress shown as you go:

[#########...............] 38.1%  7.6 GiB / 20.0 GiB  112.4 MiB/s  ETA 00:18:52

Each chunk is retried automatically if it fails. If a transfer still cannot continue, the script tells you exactly how to resume it:

Failed to write chunk 412 of 5120 at offset 1724956672 after 5 retries: aborting
Completed 1.6 GiB of 20.0 GiB
To resume, run:
  ./go2cloud-upload.sh -c 4194304 -r 5 -d 08c92dd5-70a0-4f51-83d2-835919d254df -o 1724956672 image.raw

Copy that command and run it. Do not start again from the beginning, it continues from where it stopped.

For downloads to a file you can simply run the same command again and it will pick up where it left off.

Before you download a drive

Shut the server down first. Copying a drive while its server is running gives you a crash consistent image, the same as pulling out the power cord, and it may not boot cleanly.

Image format

Only raw disk images are supported. If you have a VMDK, VHD or QCOW2 image, convert it to raw before uploading it. See converting images.

Options

All three scripts accept -h to list their options. The most useful are -c to change the chunk size, -r to change how many times a failed chunk is retried, -y to skip the confirmation prompt, and -q for quiet output when running from a script.