Winkelwagen

    Sorry, we konden geen resultaten vinden voor jouw zoekopdracht.

    TransIP REST-API: de CLI client gebruiken

    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.

    • Schakel voor je dit artikel doorloopt in je TransIP-controlepaneel de API in en genereer een key pair. Hoe dit werkt leggen wij in deze handleiding uit.
       
    • Direct zelf aan de slag? Op deze Github-pagina vind je de CLI-client terug.

    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 + > > 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 + > > 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

     

    Alle commando's zijn terug te vinden in de /src/Command directory.

    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.

    Kom je er niet uit?

    Ontvang persoonlijke hulp van onze supporters

    Neem contact op