wiki/HowtocURL.md

---
title: Howto curl
categories: tips
...

* Page de manuel : <https://curl.haxx.se/docs/manpage.html>

[curl](https://curl.haxx.se/) est un client [HTTP](HowtoHTTP) [libre](https://github.com/curl/curl/) 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 verbose 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 entê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, `-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 entête HTTP utiliser l'option `-H` (ou `--header`) :

~~~
$ curl http://www.example.com -H 'Accept: text/plain'
~~~


## 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'entête  `Host` :

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

...les inconvénients sont 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 entê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.


~~~{.bash}
#!/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 entê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'entê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'entê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 debuggage 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 !](https://twitter.com/bagder/status/788306535818625024).