Login Logout

Howto curl

curl est un client HTTP libre en ligne de commande. Il supporte aussi d’autres protocoles (HTTPS, IMAP(S), LDAP(S), POP3(S), SSCP, SFTP, SMB, SMTP(S) etc.). Il est également intégré à de nombreux langages (PHP, Python, Ruby, Perl, etc. sous forme de bibliothèque (libcurl).

Utilisation de base

Pour récupérer et afficher – sur la sortie standard – le contenu d’une ressource :

$ curl https://www.example.com

Pour afficher une version verbeuse de la requête (> Infos envoyées, < Infos reçues, * Infos supplémentaires) :

$ curl -v https://www.example.com

Pour faire une requête HEAD et donc afficher uniquement les en-têtes de la réponse, utiliser l’option -I (ou --head) :

$ curl -I www.example.com

Pour enregistrer la ressource dans un fichier portant le même nom, utiliser l’option -O (ou --remote-name) :

$ curl -O https://www.example.com/page.html

Dans le cas d’un protocole s’appuyant sur SSL/TLS, pour ne pas vérifier la validité du certificat on ajoute l’option -k (ou --insecure) :

$ curl -k https://www.example.com/

Par défaut, curl ne suit pas les redirections HTTP, il faut l’option -L (ou --location) :

$ curl -L http://www.example.com

Pour spécifier un User-Agent, utiliser l’option -A (ou --user-agent) :

$ curl -A "Mozilla/5.0 (compatible; evolix; http://evolix.com)" http://example.com 

Plus généralement, pour spécifier un en-tête HTTP utiliser l’option -H (ou --header) :

$ curl http://www.example.com -H 'Accept: text/plain'
$ curl -H 'Accept-Language: en' https://example.com

Pour envoyer un cookie dans la requête, utiliser l’option -b (ou --cookie) :

$ curl http://www.example.com -b 'key=value'

Pour l’utilisation d’un proxy :

$ curl -x http://localhost:8123 http://www.example.com

Forcer la résolution DNS

Lorsque l’on fait des tests, on a souvent besoin de forcer la résolution d’un enregistrement DNS vers une adresse IP spécifique. L’astuce classique est de modifier le fichier HOSTS (/etc/hosts sous Linux et BSD) mais cela n’est pas très pratique pour diverses raisons (nécessite un accès root, cela change pour toutes les machines, il peut y avoir du cache).

Première astuce possible, modifier l’en-tête Host :

$ curl http://192.0.2.1:8080/foo/bar -H 'Host: www.example.com'

L’inconvénient est qu’il faut modifier l’URL pour mettre l’adresse IP (ce qui ne permet pas de faire des copier/coller facilement) et que cela ne gère par le SNI (dans le cas de la couche SSL/TLS).

Une seconde astuce est d’utiliser l’option --resolve (à partir de curl 7.21.3) :

$ curl --resolve www.example.com:443:192.0.2.1 https://www.example.com/foo/bar

Utilisation avancée

Pour envoyer une authentification HTTP, préciser l’option -u (ou --user) :

$ curl -u jdoe:PASSWORD https://www.example.com

Pour spécifier la méthode HTTP POST/PUT/DELETE (par défaut GET), cela se fait avec l’option -X (ou --request) :

$ curl -X POST https://www.example.com

Attention, cette option se contente de modifier le verbe HTTP indiqué dans l’en-tête de la requête et ne modifie pas du tout le comportement de curl vis-à-vis de la réponse. Pour en savoir plus sur les bons et mauvais usages de cette option : https://daniel.haxx.se/blog/2015/09/11/unnecessary-use-of-curl-x/

Pour afficher les en-têtes et le contenu, utiliser l’option -i (ou --include) :

$ curl -i https://www.example.com

En-têtes de requête et de réponse

À placer dans un script, pour faciliter son utilisation.

Note: Ce script permet de ne pas modifier le verbe HTTP employé. En effet, une requête « HEAD » peut-être traitée différemment d’un « GET » par certains services. Il peut être combiné avec toutes les options de Curl.

#!/bin/sh
#
# https://github.com/rtomayko/dotfiles/blob/rtomayko/bin/headers

curl -sv "$@" 2>&1 >/dev/null |
  grep -v "^\*" |
  grep -v "^}" |
  cut -c3-
$ ~/bin/headers http://www.example.com
GET / HTTP/1.1
User-Agent: curl/7.38.0
Host: www.example.com
Accept: */*

HTTP/1.1 200 OK
Accept-Ranges: bytes
Cache-Control: max-age=604800
Content-Type: text/html
Date: Mon, 27 Mar 2017 12:39:35 GMT
Etag: "359670651"
Expires: Mon, 03 Apr 2017 12:39:35 GMT
Last-Modified: Fri, 09 Aug 2013 23:54:35 GMT
Server: ECS (lga/13D5)
Vary: Accept-Encoding
X-Cache: HIT
Content-Length: 1270

[data not shown]

Interactions avec une API REST

Pour tester des interactions avec une API REST, on peut facilement envoyer des structures de données.

En direct :

$ curl -XPUT 'http://localhost:9200/_snapshot/foo' -d '{
"type": "fs",
    "settings": {
        "location": "/home/backup-elasticsearch",
        "compress": true
    }
}'

Via un fichier :

$ curl -XPUT 'http://localhost:9200/_snapshot/foo' -d @/path/to/file

Version compressée

Pour obtenir le contenu gzipé (avec un en-tête HTTP forcé) :

$ curl www.example.com -H 'Accept-Encoding:gzip, deflate'

If-(M|Unm)odified-Since : contrainte sur la date de modification

Pour préciser l’en-tête HTTP If-Modified-Since et récupérer le contenu seulement si celui-ci a été modifié après le 17 Mars 2017, utiliser l’option (-z ou --time-cond) :

$ curl -z 17-Mar-17 https://www.example.com

Pour préciser l’en-tête HTTP If-Unmodified-Since et récupérer le contenu seulement si celui-ci a été modifié avant le 17 Mers 2017 :

$ curl -z -17-Mar-17 https://www.example.com

Autres protocoles

SMTP

Envoyer un email :

$ curl --mail-from foo@example.com --mail-rcpt bar@example.com smtp://example.com/

FTP

Récupérer le fichier Debian.iso via FTP :

$ curl -u jdoe:PASSWORD -O ftp://ftp.example.com/foo/bar/Debian.iso

Lister le contenu d’un dossier :

$ curl ftp://ftp.example.com/foo/bar/

Envoyer des fichiers :

$ curl -u jdoe:PASSWORD -T fichier ftp://ftp.example.com/

$ curl -u jdoe:PASSWORD -T "{fichier1,fichier2}" ftp://ftp.example.com/

FAQ

Récupérer des requêtes pour curl via un navigateur

Dans Firefox et Chrome/Chromium (et probablement d’autres) il est possible de récupérer une commande curl reprenant exactement la requête que le navigateur a faite. C’est particulièrement pratique si on veut reproduire la requête et faire un débogage plus fin. Il faut ouvrir le navigateur, dans la partie « réseau » et avec un clic-droit sur la ressource voulue, le menu déroulant proposera « Copy as curl » (ou similaire).

curl VS cURL

cURL, ou see URL (« voir URL »), est le nom général du projet, qui englobe l’outil curl et la bibliothèque libcurl comme indiqué sur https://daniel.haxx.se/docs/curl-vs-libcurl.html. Mais Daniel Steinberg, le principal auteur de curl, a dit qu’on pouvait utiliser ce qu’on veut !.