Skip to main content

Gandi command line interface

Project description

# Gandi CLI

Use `$ gandi` to easily create and manage web resources from the command line.

* `$ gandi domain` to buy and manage your domain names
* `$ gandi paas` to create and deploy your web applications
* `$ gandi vm` to spin up and upgrade your virtual machines
* `$ gandi certificate` to manage your ssl certificates
* `$ gandi` to list all available commands
* [Detailed examples](#use-cases)
* [All commands](#all-commands)

## Table of contents

* [Requirements](#requirements)
* [Installation](#installation)
* [Getting started](#getting-started)
* [Use cases](#use-cases)
* [Registering a Domain Name](#registering-a-domain-name)
* [Creating a Virtual Machine](#creating-a-virtual-machine)
* [Deploying a Web Application](#deploying-a-web-application)
* [Creating a SSL Certificate](#creating-a-ssl-certificate)
* [Creating a Private VLAN](#creating-a-private-vlan)
* [Advanced Usage](#advanced-usage)
* [All Commands](#all-commands)
* [Build manpage](#build-manpage)
* [Configuration](#configuration)
* [Development](#development)
* [Contributing](#contributing)
* [Code status](#code-status)
* [License](#license)

## Requirements

* A compatible operating system (Linux, BSD, Mac OS X/Darwin, Windows)
* Python 2.6/2.7/3.2/3.3/3.4
* openssl
* openssh
* git

Recommended tools
* [pip](https://pip.pypa.io/en/latest/installing.html)
* [virtualenv](https://virtualenv.pypa.io/en/latest/installation.html)
* docker

## Installation

### Install with pip and virtualenv

$ virtualenv /some/directory/gandi.cli
$ source /some/directory/gandi.cli/bin/activate
$ pip install gandi.cli

### Build from source

$ cd /path/to/the/repository
$ python setup.py install --user

### From the Debian package

$ ln -sf packages/debian debian && debuild -us -uc -b && echo "Bisou"

## Getting started

1. To get started, you can create a [free Gandi account](https://www.gandi.net/contact/create) and get your Gandi Handle
2. [Generate your Production API Token](https://www.gandi.net/admin/api_key) from the account admin section
3. You may also want to [top-up your prepaid account](https://www.gandi.net/prepaid)
4. To manipulate VM's, you also need to [purchase credits](https://www.gandi.net/credit/buy) (you can use funds from your prepaid account)

Then run the setup

$ gandi setup
> API Key: x134z5x4c5c # copy-paste your api key
> Environment [production] : # press enter for Production, the default
> SSH key [~/.ssh/id_rsa.pub] : # your SSH public key for hosting instances and servers

See the [Advanced Usage](#advanced-usage) section for more details on configuration.

## Use cases

* [Registering a domain name](#registering-a-domain-name)
* [Creating a virtual machine](#creating-a-virtual-machine)
* [Deploying a web application](#deploying-a-web-application)

### Registering a Domain Name

Gandi is a domain name registrar since 1999. The oldest in France and one of the world's leading, Gandi is recognized for its No Bullshit™ trademark and approach to domain names.

You can now buy and manage domains in any of the 500+ TLD's that Gandi offers from the command line.

[Know more about Gandi Domains on the website](https://www.gandi.net/domain).

#### 1. Buy a domain using the interactive prompt

$ gandi domain create
> Domain: example.com # enter the domain name here
> example.com is available
> Duration [1] : 1 # enter the duration in years

This will create a domain and use your default information for Ownership, Admin, Technical and Billing info.


#### 2. Buy a domain in one line

$ gandi domain create --domain example.com --duration 1

#### 3. Buy a domain with custom contacts

$ gandi domain create --domain example.com --duration 1 --owner XYZ123-GANDI --admin XYZ123-GANDI --tech XYZ123-GANDI --bill XYZ123-GANDI

You can use the information of Gandi handles associated to Contacts in your account to setup Owner, Admin, Technical and Billing info.

#### 3. List your domains

$ gandi domain list

#### 4. Get information about a domain

$ gandi domain info example.com

#### 5. Manage NS records for your domains

##### Create a new record

$ gandi record create example.com --name www --type A --value 127.0.0.1

Add a new record to the domain's current zone file and activate it.

##### List your records

$ gandi record list example.com

List a domain's zone file records. You can use the `--format` parameter to change the output format to `text` or `json`.

##### Update one record

$ gandi record update example.com --record "@ 3600 IN A 127.0.0.1" --new-record "@ 3600 IN A 0.0.0.0"

This command is useful to update only one record at the time. The pattern to use is `name TTL CLASS TYPE value`.

You can easily check or copy-paste the values you need to replace using the `--format text` parameter:

$ gandi record list example.com --format text


##### Update many records

$ gandi record list example.com --format text > file.zone

Use this command to extract your zone records into a file called `file.zone` (or something else).

Simply edit the file to your liking and then update the entire zone file with it.

$ gandi record update example.com -f file.zone

##### Delete records

$ gandi record delete example.com --value 127.0.0.1

Delete all records that match the given parameters from a domain's zone file. In this example, if there were many records with '127.0.0.1' as their value, all of them would be deleted.

### Creating a Virtual Machine

Gandi Server offers powerful Xen- and Linux-based virtual machines since 2007.

Virtual machines can be configured and upgraded on the fly to your liking. For example, you can start with 1GB of RAM, and run a command to add 2GB of RAM and 2 CPUs without even having to restart it.

Gandi Server measures consumption by the hour and uses a prepaid credit system. To learn more, [check out the Gandi Server website](https://www.gandi.net/hosting/server/).

#### 1. Create and access a VM

$ gandi vm create
* root user will be created.
* SSH key authorization will be used.
* No password supplied for vm (required to enable emergency web console access).
* Configuration used: 1 cores, 256Mb memory, ip v4+v6, image Debian 7, hostname: temp1415183684, datacenter: LU

Create a virtual machine with the default configuration and a random hostname.

#### 2. Upgrade a VM

$ gandi vm update temp1415183684 --memory 2048 --cores 2

Set the VM's RAM to 2GB and add a CPU core on the fly.

#### 3. Create a custom VM

$ gandi vm create --datacenter US --hostname docker --cores 2 --memory 3072 --size 10240 --image "Ubuntu 14.04 64 bits LTS (HVM)" --run "curl -sSL https://get.docker.com/ubuntu/ | sh"
* root user will be created.
* SSH key authorization will be used.
* No password supplied for vm (required to enable emergency web console access).
* Configuration used: 2 cores, 3072Mb memory, ip v4+v6, image Ubuntu 14.04 64 bits LTS, hostname: docker, datacenter: LU

This command will setup the above VM, and install docker by running `curl -sSL https://get.docker.com/ubuntu/ | sh` after creation.

#### 4. View your ressources

$ gandi vm list

#### 5. Get all the details about a VM

$ gandi vm info docker


### Deploying a Web Application

Gandi Simple Hosting is a PaaS (Platform as a Service) offering fast code deployment and easy scaling, powering over 50,000 apps since its inception in 2012.

Instances can run apps in 4 languages (PHP, Python, Node.js and Ruby) along with one of 3 popular databases (MySQL, PostgreSQL and MongoDB) and operate on a managed platform with built-in http caching.

Plans cover all scales, from small to world-class projects. [Check out the website for more information](https://www.gandi.net/hosting/simple).

#### 1. Create an instance for your app


$ gandi paas create --name myapp --type phpmysql --size S --datacenter FR --duration 1


#### 2. Update code and deploy

$ cd myapp
$ git init .
$ git add .
$ git commit -m 'first commit'
$ git push gandi master
$ gandi deploy


### Creating a SSL Certificate

Gandi SSL offers a range of SSL certificates to help you secure your projects.

You can order, obtain, update and revoke your certificates from the command line.

#### 1. Find the right plan for you


$ gandi certificate plans

Our Standard, Pro and Business plans offer different validation methods and guarantees. Each plan supports all or some of these types of certificates: single address, wildcard and/or multiple subdomains.

To discover our offering and find the right certificate for your project, [compare our plans](https://www.gandi.net/ssl/compare) and [try our simulator](https://www.gandi.net/ssl/which-ssl-certificate).

Gandi CLI can choose the right certificate type for you depending on the number of domains (altnames) you supply at creation time. You only need to set it if you plan on adding more domains to the certificate in the future.

#### 2. Create the Certificate

WARNING : This command is billable.

To request a certificate, you need to use a private key to generate and sign a CSR (Certificate Signing Request) that will be supplied to Gandi.

The `create` command will take care of this for you if you don't have them already, or you can supply your CSR directly.

Check out the examples below or [our wiki](http://wiki.gandi.net/ssl) for more information on how SSL certificates work.

To create a single domain Standard certificate:

$ gandi certificate create --cn "domain.tld"

For a wildcard Standard certificate:

$ gandi certificate create --cn "*.domain.tld"

For a multi domain Standard certificate:

$ gandi certificate create --cn "*.domain.tld" --altnames "host1.domain.tld" --altnames "host2.domain.tld"

You can also specify a plan type. For example, for a single domain Business certificate:

$ gandi certificate create --cn "domain.tld" --type "bus"

If you have a CSR (you can give the CSR content or the path):

$ gandi certificate create --csr /path/to/csr/file


#### 3. Follow the Certificate create operation


$ gandi certificate follow <operation_id>


#### 4. Get the Certificate


As soon as the operation is DONE, you can export the certificate.

$ gandi certificate export "domain.tld"


You can also retrieve intermediate certificates if needed.

$ gandi certificate export "domain.tld" --intermediate

Find information on how to use your certificate with different servers on [our wiki](http://wiki.gandi.net/en/ssl).

### Creating a private VLAN

You can use Gandi CLI to create and setup your private VLANs. For more detailed information on how VLANs and networking in general works at Gandi, please check out our resources:

* [Creating a private VLAN with Gandi CLI](http://wiki.gandi.net/en/tutorials/cli/pvlan)
* [VLAN on Gandi Wiki](http://wiki.gandi.net/en/iaas/references/network/pvlan)
* [Networking on Gandi Wiki](http://wiki.gandi.net/en/iaas/references/network)

#### Create a VLAN

$ gandi vlan create --name my-vlan-in-lu --datacenter LU \
--subnet "192.168.1.0/24" --gateway 192.168.1.1

To create a VLAN you need to determine its `name` and `datacenter`.

You can also set the `subnet` at creation time, or a default subnet will be chosen for you. The `gateway` setting is also optional and you can update both of these settings at any moment.

$ gandi vlan update my-vlan-in-lu --gateway 192.168.1.254

#### Attach an existing VM to a VLAN

To add an existing VM to a VLAN, you can create a private network interface and attach it to the VM.

$ gandi ip create --vlan my-vlan-in-lu --attach my-existing-vm --ip 192.168.1.254

If you don't specify the IP you want to use, one will be chosen for you from the VLAN's subnet.

#### Create a "Private VM"

In fact there's no such thing as a "Private VM", but you can create a VM and only attach a private interface to it.

$ gandi vm create --hostname my-private-vm --vlan my-vlan-in-lu --ip 192.168.1.2

Please note that a private VM cannot be accessed through the emergency console. You'll need a public VM that also has a private interface on the same VLAN to gain access.

You can check out [our tutorial](http://wiki.gandi.net/en/tutorials/cli/pvlan) for an example of how to achieve this.

#### More options

$ gandi vlan --help

Use the `--help` flag for more VLAN management options.


## Advanced Usage

### All Commands

To list all available commands, type `$ gandi --help`

For extended instructions, check out the `man` page.

### Build manpage

Install python-docutils and run:

$ rst2man --no-generator gandicli.man.rst > gandi.1.man

Then to read the manpage:

$ man ./gandi.1.man

### Configuration

Run `$ gandi setup` to configure your settings (see [Getting started](#getting-started))

Use `$ gandi config` to set and edit custom variables.
The default variables are:
* `sshkey` # path to your public ssh key
* `api.host` # the URL of the API endpoint to use (i.e OTE or Production)
* `api.key` # the relevant API key for the chosen endpoint


## Contributing

We <3 contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

## Code status

[![Build Status](https://travis-ci.org/Gandi/gandi.cli.svg?branch=master)](https://travis-ci.org/Gandi/gandi.cli)
[![Coverage Status](https://coveralls.io/repos/Gandi/gandi.cli/badge.svg?branch=master)](https://coveralls.io/r/Gandi/gandi.cli?branch=master)
[![Pip Version](https://pypip.in/version/gandi.cli/badge.svg)](https://pypi.python.org/pypi/gandi.cli)
[![Python Version](https://pypip.in/py_versions/gandi.cli/badge.svg)](https://pypi.python.org/pypi/gandi.cli)
[![Download Stat](https://pypip.in/download/gandi.cli/badge.svg)](https://pypi.python.org/pypi/gandi.cli)

## License / Copying

Copyright © 2014-2015 Gandi S.A.S

Gandi CLI is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

Gandi CLI is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with Gandi CLI. If not, see <http://www.gnu.org/licenses/gpl.txt>.


Changelog
=========

0.13
----

* New 'webacc' namespace for managing web accelerators for virtual machines.
* New command 'gandi status' to display Gandi services statuses.
* New command 'gandi ip update' to update reverse (PTR record)
* Update 'gandi vm create' command to add new parameter --ssh to open a SSH
session to the machine after creation is complete. This means that the
previous behavior is changed and vm creation will not automatically open a
session anymore.
* Update several commands with statistics information:
- add disk quota usage in 'gandi paas info' command
- add disk network and vm network stats in 'gandi vm info' command
* Update 'gandi account info' command to display credit usage per hour
* Update 'gandi certificate update' command to displays how to follow and
retrieve the certificate after completing the process.
* Update 'gandi ip info' command to display reverse information
* Update 'gandi ip list' command to add vlan filtering
* Update 'gandi vm list' command to add datacenter filtering
* Update 'gandi vm create' command to allow usage of a size suffix for
--size parameter (as in disk commands)
* Update 'gandi vm ssh' command to add new parameter --wait to wait for
* Update 'certificate' namespace:
- 'gandi certificate follow' command to know in which step of the process
is the current operation
- 'gandi certificate packages' display has been enhanced
- 'gandi certificate create' will try to guess the number of altnames
or wildcard
- 'gandi certificate export' will retrieve the correct intermediate
certificate.
* Update 'gandi disk attach' command to enable mounting in read-only and also
specify position where disk should be attached.
* Update 'gandi record list' command with new parameter --format
* Update 'gandi record update' command to update only one record in the zone
file
* Update 'gandi vm list' command to add datacenter filtering
* Refactor code for 'gandi ip attach' and 'gandi ip delete' commands
virtual machine sshd to come up (timeout 2min).
* Refactor 'gandi vm create' command to pass the script directly to the API
and not use scp manually after creation.
* Fixes wording and various typos in documentation and help pages.
* Add more unittests.
* Add tox and httpretty to tests packages requirements for unittests


0.12
----

* New 'ip' namespace with commands for managing public/private ip resources.
* New 'vlan' namespace with commands for managing vlans for virtual machines.
* New command 'gandi account info' to display information about credits
amount for hosting account.
* New command 'gandi contact create' to create a new contact.
* New command 'gandi disk snapshot' to create a disk snapshot on the fly.
* Update 'gandi vm create' command:
- enabling creation of vlan and ip assignment for this vlan directly
during vm creation.
- enabling creation of a private only ip virtual machine.
- parameter --ip-version is not read from configuration file anymore,
still defaulting to 4.
* Update 'gandi paas create' command to allow again the use of password provided
on the command line.
* Update 'record' namespace to add delete/update commands, with option to export
zones to file.
* Use different prefix for temporary names based on type of resource.
* Switch to use HVM image as default disk image when creating virtual machine.
* Add kernel information to output of 'gandi disk list' command.
* Fixes bug with paas vhost directory creation.
* Fixes bug with 'gandi mail delete' command raising a traceback.
* Fixes bug with duplicates entries in commands accepting multiple resources.
* Fixes various typos in documentation and help pages.
* Add first batch of unittests.


0.11
----

* New command 'gandi disk detach' to detach disks from
currently attached vm.
* New command 'gandi disk attach' to attach disk to a
vm.
* New command 'gandi disk rollback' to perform a rollback
from a snapshot.
* New parameter --source for command 'gandi disk create'
to allow creation of a new disk from an existing disk
or snapshot.
* New parameter --script for command 'gandi vm create'
to allow upload of a local script on freshly created vm
to be run after creation is completed.
* Update parameter --size of 'gandi disk create/update'
command to accept optionnal suffix: M,G,T (from megabytes
up to terabytes).
* Update command 'gandi vm ssh' to accept args to be passed
to launched ssh command.
* Fixes bug with 'gandi vm create' command and image
parameter, which failed when having more than 100 disks
in account.
* Fixes bug with 'gandi paas info' command to display
sftp_server url.
* Fixes bug with 'gandi record list' command when requesting
a domain not managed at Gandi.
* Rename --sshkey parameter of 'gandi sshkey create' command
to --filename.
* Prettify output of list/info commands.
* GANDI_CONFIG environment variable can be used to override
the global configuration file.
* Bump click requirement version to <= 4.


0.10
----

* Add new dependency to request library, for certificate
validation during xmlrpc calls.
* New command 'gandi vm kernels' to list available kernels,
can also be used to filter by vm to know which kernel is
compatible.
* New parameters --cmdline and --kernels for command
'gandi disk update' to enable updating of cmdline
and/or kernel.
* New parameter --size for command 'gandi vm create'
to specify disk size during vm creation.
* Handle max_memory setting in command 'gandi vm update'
when updating memory. New parameter --reboot added to
accept a VM reboot for non-live update.
* Update command 'gandi vm images' to also display usable
disks as image for vm creation.
* Security: validate server certificate using request as
xmlrpc transport.
* Security: restrict configuration file rights to owner only.
* Refactor code of custom parameters, to only query API when
needed, improving overall speed of all commands.
* Fixes bug with sshkey parameter for 'gandi paas create'
and 'gandi paas update' commands.
* When an API call fail, we can call again using dry-run flag
to get more explicit errors. Used by 'gandi vhost create'
command.
* Allow Gandi CLI to load custom modules using
'GANDICLI_PATH' environment variable, was previously only
done by commands.


0.9
---

* New command 'gandi docker' to manage docker instance.
This requires a docker client to work.
* Improve 'vm ssh' command to support identity file, login@
syntax.
* Login is no longer a mandatory option and saved to configuration
when creating a virtual machine.
* Add short summary to output when creating a virtual machine.
* Fixes bug when no sshkey available during setup.
* Fixes bug with parameters validation when calling a command
before having entered api credentials.

0.8
---

* New record namespace to manage domain zone record entries

0.7
---

* Add and update License information to use GPL-3
* Uniformize help strings during creation/deletion commands

0.6
---

* New mail namespace for managing mailboxes and aliases
* New command 'disk create' to create a virtual disk
* New command 'vm ssh' to open a ssh connection to an existing
virtual machine
* New command 'help' which behave like --help option.
* Using 'gandi namespace' without full command will display list
of available commands for this namespace and associated short help.
* 'gandi paas create' and 'gandi vm create' commands now use sshkeys,
and default to LU as default datacenter.

0.5
---

* Fixes Debian packaging


0.4
---

* Fixes bug with snapshotprofile list command preventing
'gandi setup' to work after clean installation
* Allow Gandi CLI to load custom modules/commands using
'GANDICLI_PATH' environment variable

0.3
---

* New certificate namespace for managing certificates
* New disk namespace for managing iaas disks
* New snapshotprofile namespace to know which profiles exists
* Allow override of configuration values for apikey, apienv and apihost
using shell environment variables API_KEY, API_ENV, API_HOST.
* Bugfixes on various vm and paas commands
* Fixes typos in docstrings
* Update man page

0.2
---

* New vhost namespace for managing virtual host for PaaS instances
* New sshkey namespace for managing a sshkey keyring
* Bugfixes on various vm and paas commands
* Bugfixes when using a hostname using only numbers
* Added a random unique name generated for temporary VM and PaaS


0.1
---

* Initial release

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gandi.cli-0.13.tar.gz (205.1 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page