TransIP stelt domein- en VPS-diensten beschikbaar via een REST API. Hierbij stuurt je website of server met behulp van je eigen scripts een verzoek direct aan het TransIP-systeem.

Een van de manieren waarop je de API kunt gebruiken, is met onze Command-Line Interface (CLI) client: TransIP-control (tipctl).

Tipctl is een tool waarmee je eenvoudig de API kunt aanspreken via command-line. Alle resources van de REST API zijn erin beschikbaar en je kunt vanuit command-line s producten bestellen, updaten of verwijderen in je TransIP-account. In dit artikel laten wij zie hoe je Tipctl installeert en gebruikt.

Vereisten

Voor het gebruik van de REST API PHP-Library moet de volgende software op je server geïnstalleerd zijn:

• PHP 7.2 of nieuwer
• PHP-json
• OpenSSL
• Composer

PHP

Voor de installatie van PHP kun je gebruik maken van onze handleidingen voor de installatie van Apache met PHP-ondersteuning. Je hebt voor de CLI-client enkel het deel nodig dat de installatie van PHP uitlegt (Apache is optioneel).

PHP-json + OpenSSL

De PHP-json extensie en OpenSSL installeer je afhankelijk van je besturingssysteem met:

CentOS:

sudo yum -y install php-json openssl

Ubuntu/Debian:

sudo apt -y install php-json openssl

Composer

Composer is een tool voor dependency management in PHP. Je kunt met Composer eenvoudig aangeven welke libraries je project nodig heeft (de dependencies) en Composer beheert deze vervolgens voor je. Voor de installatie van Composer kun je deze handleiding gebruiken.

De CLI-client installeren en configureren

Er zijn twee manieren om Tipctl te installeren: installatie via Composer of download en installatie van het PHAR-bestand. Heb je nog geen Composer geïnstalleerd? Voor installatie van Composer in Linux kun je deze handleiding gebruiken.

Voor het gebruik van het PHAR-bestand, moet je ./ voor het commando plaatsen om aan te geven dat je het uitvoert vanuit je hudige directory. Wil je tipctl.phar globaal kunnen gebruiken? Dan raden wij aan om de Composer-installatie te gebruiken. Alternatief kun je een alias aanmaken voor het PHAR-bestand, zie de stappen hieronder.

Installatie met Composer

Stap 1

Voor de installatie van Tipctl met Composer gebruik je het volgende commando:

composer global require transip/tipctl

Stap 2

Voeg vervolgens de global vendor binaries folder toe aan de $PATH variabele. Je kunt hiervoor controleren wat de directory is met het commando:

composer global config bin-dir --absolute

Stel dat bijvoorbeeld /home/transip/.config/composer/ als output terug komt. Dan zou je /home/transip/.config/composer/vendor/bin/ aan $PATH toevoegen. Dit kun je bijvoorbeeld doen als volgt:

nano ~/.bash_profile

Pas in het geopende bestand de PATH= regel aan zodat de bin directory daar in is toegevoegd. Het resultaat kan er dan als volgt uitzien:

PATH=$PATH:$HOME/.local/bin:$HOME/bin:/home/transip/.config/composer/vendor/bin/

Sla de wijzigingen op en sluit het bestand met ctrl + x > y > enter.

Stap 3

Verwerk de wijzigingen vervolgens met:

source ~/.bash_profile

Je kunt daarna direct Tipctl testen met het commando:

tipctl --version

Download en installatie van het PHAR-bestand

Stap 1

Download Tipctl met het commando:

wget https://github.com/transip/tipctl/releases/download/v6.0.0/tipctl.phar

Stap 2

Maak het bestand uitvoerbaar:

chmod +x ./tipctl.phar

Stap 3

Je kunt nu de werking testen, bijvoorbeeld met het commando:

./tipctl.phar --version

Stap 4 - Optioneel

Optioneel kun je een alias instellen voor het gebruik van tipctl.phar. Met een alias stel je als het ware een shortcut in voor een commando (of aantal commando's). Let wel dat dit enkel werkt vanuit command-line en niet vanuit shell-scripts, cronjobs, etc.

Open het bestand ~/.bashrc (het bestand met het shell configuratie profiel van de gebruiker):

nano ~/.bashrc

Stap 5 - Optioneel

Afhankelijk van je besturingssysteem zie je of een relatief leeg (CentOS) of gevuld (Debian, Ubuntu) bestand. Voeg onderaan het bestand de volgende code toe:

alias tipctl='~/bin/tipctl.phar'

Vervang hier de directory door de plaats waar op je VPS je tipctl.phar hebt staan. Sluit vervolgens het bestand en sla de wijzigingen op (ctrl + x > y > enter).

Stap 6 - Optioneel

De wijzigingen worden na een reboot verwerkt, of gebruik het volgende commando om de wijzigingen direct te verwerken.

source ~/.bashrc

De eerste setup

Voor je Tipctl kunt gebruiken, doorloop je de setup om je TransIP-account aan Tipctl te koppelen.

Stap 1

Start de setup met:

tipctl setup

Stap 2

Een voor een krijg je de volgende stappen te zien:

Enter the RestAPI url [https://api.transip.nl/v6]:
Enter your TransIP Username []: jetransipaccount
Use IP Whitelisting? [Yes]:
Enter your RestAPI Private Key:
-----BEGIN PRIVATE KEY-----MIIEvgIkWyaxuFA977cDw6Kn-----END PRIVATE KEY-----
Checking API connection to endpoint 'https://api.transip.nl/v6'

API connection successful
Config file saved in /home/transip/.config/transip-api/cli-config.json

• Enter the RestAPI url: Druk op 'Enter' om de URL tussen de brackets te gebruiken.
• Enter your TransIP Username: Geef de naam van je TransIP-account op.
• Use IP Whitelisting: Druk op 'Enter' om whitelisting te gebruiken (default waarde). Type 'no' als je whitelisting uit hebt gezet voor de API in het TransIP-controlepaneel.
• Enter your RestAPI Private Key: Dit is de private key die je op de API-pagina in het TransIP-controlepaneel genereert, zie onze algemene API-handleiding.

De CLI-client gebruiken

Nu de alias is ingesteld kun je de CLI-client aanroepen met het commando:

tipctl

Je krijgt als output een overzicht te zien van alle beschikbare commando's. Zoek je een specifieke optie, bijvoorbeeld om DNS te wijzigen? Gebruik dan 'grep', bijvoorbeeld:

tipctl | grep dns

Alle beschikbare commando's voer je eenvoudig uit met de syntax:

tipctl product:commandonaam

Bijvoorbeeld:

tipctl vps:start

Wil je weten welke variabelen je mee moet geven? Voeg dan -h toe aan het commando:

tipctl -h vps:start

De output hiervan zal er als volgt uitzien:

tipctl -h vps:start

The output of this will look like this:

Description:
  Start a Vps

Usage:
  vps:start [options] [--] <VpsName>

Arguments:
  VpsName                The name of the vps

Options:
      --format[=FORMAT]  The output format `txt`, `yaml` or `json` [default: "json"]
  -h, --help             Display this help message
  -q, --quiet            Do not output any message
  -V, --version          Display this application version
      --ansi             Force ANSI output
      --no-ansi          Disable ANSI output
  -n, --no-interaction   Do not ask any interactive question
  -v|vv|vvv, --verbose   Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  Provide a Vps name to start

Veiligheidsoverwegingen

De command-line client is een zeer krachtige tool voor het gebruik van onze REST API. De installatie is eenvoudig en de client is precompiled. Je hoeft enkel één commando uit te voeren om een overzicht te krijgen van alle beschikbare functies binnen de REST API.

Het maakt met de CLI-client niet langer uit welke programmeertaal je gebruikt. Zo lang de taal die je gebruikt maar een shell-commando kan uitvoeren vanaf de server die je applicatie host, kun je de client daarmee aanroepen.

Wij raden echter aan Tipctl vooral voor troubleshooting en beheer vanuit command-line te gebruiken en voor daadwerkelijke toepassingen in een applicatie bijvoorbeeld de Rest API met PHP of Curl te gebruiken.

Wil je toch Tipctl aanroepen vanuit je applicatie, is het belangrijk rekening te houden met het volgende veiligheidsrisico: Als je toestaat dat een commando aangepast kan worden via gebruikersinput, kunnen er schadelijke commando's toevoegd worden. Zorg daarom dat je altijd eventuele gebruikersinput escaped (tussen haakjes plaatst), zodat commando's als string worden gelezen en niet daadwerkelijk als commando worden uitgevoerd.

Daarmee zijn we aan het eind gekomen van deze handleiding over het gebruik van onze API command-line client Tipctl. Mocht je aan de hand van deze handleiding nog vragen hebben, aarzel dan niet om onze supportafdeling te benaderen. Je kunt hen bereiken via de knop 'Neem contact op' onderaan deze pagina.